home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d12 / scl120.arc / SCL120.DOC < prev    next >
Text File  |  1990-09-07  |  443KB  |  15,910 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.                               SCL1 C - FUNCTION LIBRARY
  29.  
  30.                                      VERSION 2.0
  31.  
  32.                                   REFERENCE MANUAL
  33.  
  34.                              COPYRIGHT (C) 1989,1990 BY:
  35.  
  36.                                 JOSE RODRIGUEZ ALVIRA
  37.                                          AND
  38.                                    JOSE R. LEBRON
  39.  
  40.  
  41.  
  42.  
  43.  
  44.                           SCL1 Version 2.0 Reference Manual
  45.  
  46.  
  47.                                   TABLE OF CONTENTS
  48.  
  49.           OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . .    1
  50.  
  51.           DISCLAIMER . . . . . . . . . . . . . . . . . . . . . . . . .    2
  52.  
  53.           USING SCL1 . . . . . . . . . . . . . . . . . . . . . . . . .    3
  54.  
  55.           WHAT IS SSG  . . . . . . . . . . . . . . . . . . . . . . . .    3
  56.  
  57.           SCL1DEMO . . . . . . . . . . . . . . . . . . . . . . . . . .    3
  58.  
  59.           FUNCTION REFERENCE . . . . . . . . . . . . . . . . . . . . .    4
  60.  
  61.           ALPHABETICAL REFERENCE . . . . . . . . . . . . . . . . . . .    5
  62.                AddExtension  . . . . . . . . . . . . . . . . . . . . .    5
  63.                BackgroundOff . . . . . . . . . . . . . . . . . . . . .    6
  64.                BackgroundOn  . . . . . . . . . . . . . . . . . . . . .    7
  65.                Beep  . . . . . . . . . . . . . . . . . . . . . . . . .    8
  66.                BigCursor . . . . . . . . . . . . . . . . . . . . . . .    9
  67.                Bin2Ascii . . . . . . . . . . . . . . . . . . . . . . .   10
  68.                Box . . . . . . . . . . . . . . . . . . . . . . . . . .   11
  69.                Buf2Disk  . . . . . . . . . . . . . . . . . . . . . . .   13
  70.                Calendar  . . . . . . . . . . . . . . . . . . . . . . .   14
  71.                Center  . . . . . . . . . . . . . . . . . . . . . . . .   18
  72.                ChangeDumpColor . . . . . . . . . . . . . . . . . . . .   19
  73.                ChangeExtension . . . . . . . . . . . . . . . . . . . .   20
  74.                CheckBarMenu  . . . . . . . . . . . . . . . . . . . . .   21
  75.                CheckChar . . . . . . . . . . . . . . . . . . . . . . .   23
  76.                CheckItemList . . . . . . . . . . . . . . . . . . . . .   24
  77.                CheckMouse  . . . . . . . . . . . . . . . . . . . . . .   26
  78.                CheckMouseButton  . . . . . . . . . . . . . . . . . . .   27
  79.                ClearKeyBuf . . . . . . . . . . . . . . . . . . . . . .   29
  80.                CloseFile . . . . . . . . . . . . . . . . . . . . . . .   30
  81.                Cls . . . . . . . . . . . . . . . . . . . . . . . . . .   31
  82.                CreateFile  . . . . . . . . . . . . . . . . . . . . . .   32
  83.                CursorOff . . . . . . . . . . . . . . . . . . . . . . .   33
  84.                CursorOn  . . . . . . . . . . . . . . . . . . . . . . .   33
  85.                DeleteFile  . . . . . . . . . . . . . . . . . . . . . .   34
  86.                DialogBox . . . . . . . . . . . . . . . . . . . . . . .   35
  87.                DisableMouse  . . . . . . . . . . . . . . . . . . . . .   36
  88.                DrawBarMenu . . . . . . . . . . . . . . . . . . . . . .   37
  89.                DrawBoxLine . . . . . . . . . . . . . . . . . . . . . .   39
  90.                DrawItemList  . . . . . . . . . . . . . . . . . . . . .   40
  91.                DrawLine  . . . . . . . . . . . . . . . . . . . . . . .   42
  92.                DrawMouseButton . . . . . . . . . . . . . . . . . . . .   43
  93.                ErrorBox  . . . . . . . . . . . . . . . . . . . . . . .   45
  94.                ErrorShadowOff  . . . . . . . . . . . . . . . . . . . .   47
  95.                ErrorShadowOn . . . . . . . . . . . . . . . . . . . . .   47
  96.  
  97.                                       Page -i-
  98.  
  99.  
  100.  
  101.  
  102.  
  103.                           SCL1 Version 2.0 Reference Manual
  104.  
  105.  
  106.                                   TABLE OF CONTENTS
  107.  
  108.                FieldCheck  . . . . . . . . . . . . . . . . . . . . . .   48
  109.                Fields  . . . . . . . . . . . . . . . . . . . . . . . .   50
  110.                Fields2 . . . . . . . . . . . . . . . . . . . . . . . .   54
  111.                FileBox . . . . . . . . . . . . . . . . . . . . . . . .   62
  112.                FileBox2  . . . . . . . . . . . . . . . . . . . . . . .   63
  113.                File2Buf  . . . . . . . . . . . . . . . . . . . . . . .   66
  114.                FillBlock . . . . . . . . . . . . . . . . . . . . . . .   68
  115.                FindFirst . . . . . . . . . . . . . . . . . . . . . . .   69
  116.                FindNext  . . . . . . . . . . . . . . . . . . . . . . .   69
  117.                GetCurCol . . . . . . . . . . . . . . . . . . . . . . .   73
  118.                GetCurLine  . . . . . . . . . . . . . . . . . . . . . .   73
  119.                GetCurrentDir . . . . . . . . . . . . . . . . . . . . .   74
  120.                GetCurSize  . . . . . . . . . . . . . . . . . . . . . .   75
  121.                GetDate . . . . . . . . . . . . . . . . . . . . . . . .   76
  122.                GetDefaultDrive . . . . . . . . . . . . . . . . . . . .   78
  123.                GetDiskFreeSpace  . . . . . . . . . . . . . . . . . . .   79
  124.                GetExtendedAscii  . . . . . . . . . . . . . . . . . . .   80
  125.                GetFiles  . . . . . . . . . . . . . . . . . . . . . . .   82
  126.                GetFileMode . . . . . . . . . . . . . . . . . . . . . .   83
  127.                GetFilePt . . . . . . . . . . . . . . . . . . . . . . .   85
  128.                GetFileSize . . . . . . . . . . . . . . . . . . . . . .   87
  129.                GetFreeMem  . . . . . . . . . . . . . . . . . . . . . .   89
  130.                GetKey  . . . . . . . . . . . . . . . . . . . . . . . .   90
  131.                GetString . . . . . . . . . . . . . . . . . . . . . . .   91
  132.                GetTime . . . . . . . . . . . . . . . . . . . . . . . .   93
  133.                GSSBox  . . . . . . . . . . . . . . . . . . . . . . . .   94
  134.                HideMouse . . . . . . . . . . . . . . . . . . . . . . .   96
  135.                InitMouse . . . . . . . . . . . . . . . . . . . . . . .   97
  136.                InitUserError . . . . . . . . . . . . . . . . . . . . .   98
  137.                InitVideo . . . . . . . . . . . . . . . . . . . . . . .  100
  138.                KeyReady  . . . . . . . . . . . . . . . . . . . . . . .  102
  139.                KeyStatus . . . . . . . . . . . . . . . . . . . . . . .  103
  140.                LineEditor  . . . . . . . . . . . . . . . . . . . . . .  104
  141.                ListManager . . . . . . . . . . . . . . . . . . . . . .  111
  142.                ListWindow  . . . . . . . . . . . . . . . . . . . . . .  113
  143.                MakeDir . . . . . . . . . . . . . . . . . . . . . . . .  120
  144.                Menu  . . . . . . . . . . . . . . . . . . . . . . . . .  121
  145.                MenuSys . . . . . . . . . . . . . . . . . . . . . . . .  123
  146.                MenuSystem  . . . . . . . . . . . . . . . . . . . . . .  128
  147.                MessageOff  . . . . . . . . . . . . . . . . . . . . . .  138
  148.                MessageOn . . . . . . . . . . . . . . . . . . . . . . .  139
  149.                MessageShadowOff  . . . . . . . . . . . . . . . . . . .  140
  150.                MessageShadowOn . . . . . . . . . . . . . . . . . . . .  140
  151.                MouseButton . . . . . . . . . . . . . . . . . . . . . .  141
  152.                MouseMenu . . . . . . . . . . . . . . . . . . . . . . .  145
  153.                MoveFilePt  . . . . . . . . . . . . . . . . . . . . . .  148
  154.                MoveFilePt2Off  . . . . . . . . . . . . . . . . . . . .  150
  155.  
  156.                                       Page -ii-
  157.  
  158.  
  159.  
  160.  
  161.  
  162.                           SCL1 Version 2.0 Reference Manual
  163.  
  164.  
  165.                                   TABLE OF CONTENTS
  166.  
  167.                OpenFile  . . . . . . . . . . . . . . . . . . . . . . .  152
  168.                PushCursor  . . . . . . . . . . . . . . . . . . . . . .  154
  169.                PopCursor . . . . . . . . . . . . . . . . . . . . . . .  154
  170.                PopMenu . . . . . . . . . . . . . . . . . . . . . . . .  155
  171.                ReadFile  . . . . . . . . . . . . . . . . . . . . . . .  157
  172.                RemoveDir . . . . . . . . . . . . . . . . . . . . . . .  158
  173.                RemoveExtension . . . . . . . . . . . . . . . . . . . .  159
  174.                RenameFile  . . . . . . . . . . . . . . . . . . . . . .  160
  175.                ResetMouse  . . . . . . . . . . . . . . . . . . . . . .  161
  176.                ResetMouseCur . . . . . . . . . . . . . . . . . . . . .  162
  177.                ScreenDump  . . . . . . . . . . . . . . . . . . . . . .  163
  178.                ScrollDown  . . . . . . . . . . . . . . . . . . . . . .  164
  179.                ScrollList  . . . . . . . . . . . . . . . . . . . . . .  165
  180.                ScrollUp  . . . . . . . . . . . . . . . . . . . . . . .  167
  181.                ScrollWindow  . . . . . . . . . . . . . . . . . . . . .  168
  182.                Select  . . . . . . . . . . . . . . . . . . . . . . . .  176
  183.                SetCurPos . . . . . . . . . . . . . . . . . . . . . . .  180
  184.                SetCurSize  . . . . . . . . . . . . . . . . . . . . . .  181
  185.                SetDialogColor  . . . . . . . . . . . . . . . . . . . .  182
  186.                SetErrorBoxColor  . . . . . . . . . . . . . . . . . . .  183
  187.                SetFileMode . . . . . . . . . . . . . . . . . . . . . .  184
  188.                SetHorLimit . . . . . . . . . . . . . . . . . . . . . .  186
  189.                SetInt24Color . . . . . . . . . . . . . . . . . . . . .  187
  190.                SetMouseCur . . . . . . . . . . . . . . . . . . . . . .  188
  191.                SetMouseIsr . . . . . . . . . . . . . . . . . . . . . .  189
  192.                SetMousePos . . . . . . . . . . . . . . . . . . . . . .  191
  193.                SetShadowColor  . . . . . . . . . . . . . . . . . . . .  192
  194.                SetUserBox  . . . . . . . . . . . . . . . . . . . . . .  193
  195.                SetUserBoxLine  . . . . . . . . . . . . . . . . . . . .  195
  196.                SetVerLimit . . . . . . . . . . . . . . . . . . . . . .  196
  197.                SetVideoMode  . . . . . . . . . . . . . . . . . . . . .  197
  198.                SetVideoPage  . . . . . . . . . . . . . . . . . . . . .  198
  199.                SetVideo4350  . . . . . . . . . . . . . . . . . . . . .  199
  200.                SetVideo25  . . . . . . . . . . . . . . . . . . . . . .  199
  201.                Shadow  . . . . . . . . . . . . . . . . . . . . . . . .  200
  202.                ShowMouse . . . . . . . . . . . . . . . . . . . . . . .  201
  203.                SortPointers  . . . . . . . . . . . . . . . . . . . . .  202
  204.                Sound . . . . . . . . . . . . . . . . . . . . . . . . .  203
  205.                SoundOff  . . . . . . . . . . . . . . . . . . . . . . .  204
  206.                SoundOn . . . . . . . . . . . . . . . . . . . . . . . .  204
  207.                StopWatch . . . . . . . . . . . . . . . . . . . . . . .  205
  208.                TagItem . . . . . . . . . . . . . . . . . . . . . . . .  206
  209.                TagList . . . . . . . . . . . . . . . . . . . . . . . .  209
  210.                TagList2  . . . . . . . . . . . . . . . . . . . . . . .  211
  211.                TagMenu . . . . . . . . . . . . . . . . . . . . . . . .  215
  212.                Textwindow  . . . . . . . . . . . . . . . . . . . . . .  218
  213.                TrapInt23 . . . . . . . . . . . . . . . . . . . . . . .  222
  214.  
  215.                                      Page -iii-
  216.  
  217.  
  218.  
  219.  
  220.  
  221.                           SCL1 Version 2.0 Reference Manual
  222.  
  223.  
  224.                                   TABLE OF CONTENTS
  225.  
  226.                TrapInt24 . . . . . . . . . . . . . . . . . . . . . . .  223
  227.                TSound  . . . . . . . . . . . . . . . . . . . . . . . .  224
  228.                Video . . . . . . . . . . . . . . . . . . . . . . . . .  225
  229.                VideoConfig . . . . . . . . . . . . . . . . . . . . . .  226
  230.                WaitKeyMouse  . . . . . . . . . . . . . . . . . . . . .  228
  231.                WaitTime  . . . . . . . . . . . . . . . . . . . . . . .  228
  232.                WFileBox  . . . . . . . . . . . . . . . . . . . . . . .  229
  233.                Window  . . . . . . . . . . . . . . . . . . . . . . . .  232
  234.                WriteChar . . . . . . . . . . . . . . . . . . . . . . .  234
  235.                WriteFile . . . . . . . . . . . . . . . . . . . . . . .  235
  236.                WriteOffLen . . . . . . . . . . . . . . . . . . . . . .  236
  237.                WriteOffset . . . . . . . . . . . . . . . . . . . . . .  237
  238.                WriteScreen . . . . . . . . . . . . . . . . . . . . . .  238
  239.                WriteScreen . . . . . . . . . . . . . . . . . . . . . .  239
  240.                YesNo . . . . . . . . . . . . . . . . . . . . . . . . .  241
  241.                YesNoShadowOff  . . . . . . . . . . . . . . . . . . . .  242
  242.                YesNoShadowOn . . . . . . . . . . . . . . . . . . . . .  242
  243.  
  244.           APPENDIX "A" - FILE RELATED FUNCTIONS  . . . . . . . . . . .  243
  245.  
  246.           APPENDIX "B" - MOUSE FUNCTIONS . . . . . . . . . . . . . . .  246
  247.  
  248.           APPENDIX "C" - SCREEN RELATED FUNCTIONS  . . . . . . . . . .  248
  249.  
  250.           APPENDIX "D" - SCL1 HEADER FILES . . . . . . . . . . . . . .  250
  251.  
  252.           APPENDIX "E" - DIALOG TYPE FUNCTIONS . . . . . . . . . . . .  251
  253.  
  254.           APPENDIX "F" - CHANGES IN SCL1 VERSION 2.0 . . . . . . . . .  262
  255.  
  256.           REGISTRATION INFORMATION . . . . . . . . . . . . . . . . . .  265
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.                                       Page -iv-
  275.  
  276.  
  277.  
  278.  
  279.  
  280.                           SCL1 Version 2.0 Reference Manual
  281.  
  282.           OVERVIEW
  283.  
  284.           The functions included here provide an alternative to the
  285.           standard C-library functions.  Extensive screen handling and
  286.           mouse handling functions are provided that are not found in the
  287.           standard library.  Every effort has been made to exploit the PC
  288.           hardware to its maximum capacity, portability has not been a
  289.           primary goal.  The library is designed to work with the Microsoft
  290.           and the Borland Turbo-C C Compilers.  The Shareware version
  291.           contains stand alone small memory model libraries for both
  292.           compilers.
  293.  
  294.           You do not need to understand the internal workings of the
  295.           functions in order to take full advantage of them, all you need
  296.           to know is how to call them and how to pass the required
  297.           parameters.
  298.  
  299.           SCL1 is distributed under the Shareware concept.  Feel free to
  300.           try it, if you like and use the product please register your
  301.           copy.  Upon registration you will receive the following:
  302.  
  303.                1.   The latest version of SCL1.
  304.  
  305.                2.   Library modules for the small, medium, compact and
  306.                     large and huge memory models for the compiler of your
  307.                     choice.
  308.  
  309.                3.   SSG, a screen editor and program generator for use with
  310.                     SCL1. (see the included SSG Reference Manual)
  311.  
  312.                4.   You will be notified of all updates, additions and
  313.                     revisions.
  314.  
  315.           Feel free to distribute the Shareware version of SCL1 for trial
  316.           use by others on a private non-commercial basis.  The only
  317.           distribution conditions are: that the code must not be modified
  318.           or altered, and that no fee (except the nominal cost of
  319.           distribution) may be charged.
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.                                       Page -1-
  334.  
  335.  
  336.  
  337.  
  338.  
  339.                           SCL1 Version 2.0 Reference Manual
  340.  
  341.           DISCLAIMER
  342.  
  343.           The functions included in this package are, to the best of our
  344.           knowledge, original or use standard accepted algorithms.  We make
  345.           no claim that these functions are optimized or totally suited for
  346.           commercial use.  They have been thoroughly tested and, to the
  347.           best of our knowledge, perform as this documentation describe. 
  348.           We cannot  accept any responsibility for any problems which may
  349.           occur through the use of these functions for any application. 
  350.           After examining this document or the demo files included, if you
  351.           feel that this package is not suitable for your use, please do
  352.           not use it.
  353.  
  354.           THIS SOFTWARE AND MANUAL ARE SOLD "AS IS" AND WITHOUT WARRANTIES
  355.           AS TO PERFORMANCE OF MERCHANTABILITY OR ANY OTHER WARRANTIES
  356.           WHETHER EXPRESSED OR IMPLIED.  BECAUSE OF THE VARIOUS HARDWARE
  357.           AND SOFTWARE ENVIRONMENTS INTO WHICH THIS PROGRAM MAY BE PUT, NO
  358.           WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE IS OFFERED.
  359.  
  360.           GOOD DATA PROCESSING PROCEDURE DICTATES THAT ANY PROGRAM BE
  361.           THOROUGHLY TESTED WITH NON-CRITICAL DATA BEFORE RELYING ON IT. 
  362.           THE USER MUST ASSUME THE ENTIRE RISK OF USING THE PROGRAM.  ANY
  363.           LIABILITY OF THE SELLER WILL BE LIMITED EXCLUSIVELY TO PRODUCT
  364.           REPLACEMENT OR REFUND OF PURCHASE PRICE.
  365.  
  366.           Feel free to send any comments or suggestions even if you do not
  367.           decide to register your copy.  If you find any bugs please let us
  368.           know so that they can be traced and fixed.  Please include with
  369.           your comments any relevant information, such as; hardware
  370.           configuration, description of the bug or problem and if possible
  371.           a section of the problem code.  Currently we can only support
  372.           this program by mail.
  373.  
  374.           INSTALLING SCL1
  375.  
  376.           All the files that are required to install SCL1 are distributed
  377.           in a compressed self extracting form.  You can use the included
  378.           INSTALL.EXE program to perform the installation or you can
  379.           manually decompress and copy them to the corresponding drives or
  380.           directories.  If you are using Microsoft C or Quick C copy the
  381.           library files starting with M to the drive or directory where you
  382.           have all your library files and the header file to the drive or
  383.           directory where you have your include files.  If you are using
  384.           Turbo C use the files starting with T instead. The library files
  385.           for the different memory models are identified with the last
  386.           letter.
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                                       Page -2-
  393.  
  394.  
  395.  
  396.  
  397.  
  398.                           SCL1 Version 2.0 Reference Manual
  399.  
  400.           USING SCL1
  401.  
  402.           To use SCL1 make sure you include the preprocessor directive;
  403.           #include <SCL1.H> in your program.  Several other header files
  404.           are included with the keys, colors and music notes definitions.
  405.  
  406.           WHAT IS SSG
  407.  
  408.           You can really take the most advantage of SCL1 with an auxiliary
  409.           program called SSG.  SSG is a full featured screen editor and
  410.           program generator.  It will provide the required tools for
  411.           building program screens and menus.  After you design your
  412.           screen, you instruct SSG about the desired operations you want to
  413.           perform, such as: saving the screen contents, making a window,
  414.           clearing all or part of the screen, making a menu, etc.  Then SSG
  415.           will write the C code for the desired operations using the
  416.           functions available in SCL1.  You can merge the generated code
  417.           into your program.  SSG will help you in speeding the most time
  418.           consuming tasks during programming.
  419.  
  420.           A demo of SSG and its complete documentation is included in the
  421.           Shareware version of SCL1.  Upon registration you will receive a
  422.           full working copy of SSG.
  423.  
  424.           SCL1DEMO
  425.  
  426.           The program SCL1DEMO demonstrates some of the functions
  427.           available.  It was written using SCL1 with the help of SSG.  The
  428.           best way to discover about SCL1's features is to run this demo. 
  429.           To start the demo type SCL1DEMO at the DOS prompt.  You can
  430.           obtain the source code for the Demo program by calling TECH-BBS,
  431.           see Appendix "F".
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.                                       Page -3-
  452.  
  453.  
  454.  
  455.  
  456.  
  457.                           SCL1 Version 2.0 Reference Manual
  458.  
  459.  
  460.           FUNCTION REFERENCE
  461.  
  462.           An alphabetical reference of all the functions is included in
  463.           this documentation manual.  The reference provide full a
  464.           description of each function.  A uniform format has been used in
  465.           this reference.  At the top right corner of each page the name of
  466.           the function or functions discussed in that page are shown to let
  467.           you quickly locate a desired function.  The format used is as
  468.           follows:
  469.  
  470.                                                               Function Name
  471.  
  472.           Function:    Function Name
  473.  
  474.           Purpose:     A description of what the function does.
  475.  
  476.           Declaration: Function prototype.  The parameters types are shown. 
  477.                        All the function prototypes have been included in
  478.                        the header file SCL1.H so it is not necessary to
  479.                        declare them in your programs.
  480.  
  481.           Returns:     What the function returns.
  482.  
  483.           Parameters:  A description of the parameters, structures, arrays,
  484.                        buffers, etc. required by the function are
  485.                        explained.
  486.  
  487.           Messages:    In the dialog type functions, messages are exchanged
  488.                        with the function.  This section describe these
  489.                        messages.
  490.  
  491.           Example:     A short example of the function usage.
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.                                       Page -4-
  511.  
  512.  
  513.  
  514.  
  515.  
  516.                           SCL1 Version 2.0 Reference Manual
  517.  
  518.  
  519.                                ALPHABETICAL REFERENCE
  520.  
  521.                                                                AddExtension
  522.  
  523.           Function:    AddExtension
  524.  
  525.           Purpose:     Adds an extension to a filename if the filename has
  526.                        no extension and does not end with a period.
  527.  
  528.           Declaration: char *AddExtension(char *Filename, char *Extension);
  529.  
  530.           Returns:     The return value is a pointer to the filename
  531.                        buffer.
  532.  
  533.           Parameters:
  534.  
  535.               Filename - char pointer to filename.
  536.  
  537.              Extension - char pointer to string holding the extension.
  538.  
  539.           Example:
  540.  
  541.           #include <scl1.h>
  542.  
  543.           char Filename[13]="FILE";
  544.  
  545.           main()
  546.              {
  547.              printf("%s\n",Filename);
  548.              printf("%s\n",AddExtension(Filename,"C"));
  549.              }
  550.  
  551.           See also ChangeExtension and RemoveExtension
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.                                       Page -5-
  570.  
  571.  
  572.  
  573.  
  574.  
  575.                           SCL1 Version 2.0 Reference Manual
  576.  
  577.  
  578.                                                               BackgroundOff
  579.  
  580.           Function:    BackgroundOff
  581.  
  582.           Purpose:     Stops a function running in the background.
  583.  
  584.           Declaration: void BackgroundOff(void);
  585.  
  586.           Returns:     Nothing
  587.  
  588.           Parameters:  None
  589.  
  590.           Example:
  591.  
  592.           #include <slc1.h>
  593.  
  594.           main()
  595.              {
  596.              BackgroundOn(B_Function);
  597.              .
  598.              .
  599.              BackgroundOff();
  600.              }
  601.  
  602.           Notes:
  603.  
  604.              It is very important to stop any background running function
  605.              before returning to DOS.  Failure to do so can result in a
  606.              system crash.
  607.  
  608.           See also BackgroundOn.
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.                                       Page -6-
  629.  
  630.  
  631.  
  632.  
  633.  
  634.                           SCL1 Version 2.0 Reference Manual
  635.  
  636.  
  637.                                                                BackgroundOn
  638.  
  639.           Function:    BackgroundOn
  640.  
  641.           Purpose:     Makes a function share microprocessor time with a
  642.                        main process (run in the background).
  643.  
  644.           Declaration: void BackgroundOn(int (*FAddress)());
  645.  
  646.           Returns:     Nothing
  647.  
  648.           Parameters:
  649.  
  650.               FAddress - Pointer to the function that will be set to run in
  651.                          the background.  It will be called 18.2 times per
  652.                          second.
  653.  
  654.           Example:
  655.  
  656.           #include <slc1.h>
  657.  
  658.           main()
  659.              {
  660.              BackgroundOn(B_Function);
  661.              .
  662.              .
  663.              BackgroundOff();
  664.              }
  665.  
  666.           Notes:
  667.  
  668.              Functions that run in the background mode must not perform
  669.              disk or keyboard input/output or call any time or sound
  670.              related function.  You should avoid using any standard library
  671.              function that calls DOS or that uses the stack heavily. 
  672.              SCL1's screen related functions (except GSSBox) and the
  673.              standard library data manipulation functions are generally
  674.              safe to use in background mode.  Background functions are
  675.              called 18.2 per second.  Each time they are called they should
  676.              do as little as possible and return control to the calling
  677.              routine.
  678.  
  679.              If you are using a Microsoft compiler you might need to
  680.              disable the compiler's stack checking option using the
  681.              "#pragma check_stack(off)" directive.
  682.  
  683.  
  684.  
  685.  
  686.  
  687.                                       Page -7-
  688.  
  689.  
  690.  
  691.  
  692.  
  693.                           SCL1 Version 2.0 Reference Manual
  694.  
  695.  
  696.                                                                        Beep
  697.  
  698.           Function:    Beep
  699.  
  700.           Purpose:     Sends a beep tone to the console speaker.
  701.  
  702.           Declaration: void Beep(void);
  703.  
  704.           Returns:     Nothing
  705.  
  706.           Parameters:  None
  707.  
  708.           Example:
  709.  
  710.           #include <scl1.h>
  711.  
  712.           main()
  713.              {
  714.              Beep();   /* Sends a short beep to the console.*/
  715.              }
  716.           See also SoundOn, SoundOff and TSound
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.                                       Page -8-
  747.  
  748.  
  749.  
  750.  
  751.  
  752.                           SCL1 Version 2.0 Reference Manual
  753.  
  754.  
  755.                                                                   BigCursor
  756.  
  757.           Function:    BigCursor
  758.  
  759.           Purpose:     Changes the cursor size to a block.
  760.  
  761.           Declaration: void BigCursor(void);
  762.  
  763.           Returns:     Nothing
  764.  
  765.           Parameters:  None
  766.  
  767.           Example:
  768.  
  769.           #include <scl1.h>
  770.  
  771.           main()
  772.              {
  773.              BigCursor(); /* Turns the cursor to a block. */
  774.              }
  775.  
  776.           See also SetCurSize, GetCurCol, GetCurLine.
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.                                       Page -9-
  806.  
  807.  
  808.  
  809.  
  810.  
  811.                           SCL1 Version 2.0 Reference Manual
  812.  
  813.  
  814.                                                                   Bin2Ascii
  815.  
  816.           Function:    Bin2Ascii
  817.  
  818.           Purpose:     Fills a buffer with the ASCII code of a long integer
  819.                        value, adding commas, (i.e. 12,345). The buffer must
  820.                        be big enough to hold all characters plus commas and
  821.                        a zero (for terminating the string).
  822.  
  823.           Declaration: char *Bin2Ascii(long Number,char * Buffer);
  824.  
  825.           Returns:     The return value is a pointer to the buffer.
  826.  
  827.           Parameters:
  828.  
  829.                 Number - number whose ASCII value is to be written into the
  830.                          buffer (long integer).
  831.  
  832.                 Buffer - char pointer to the buffer to hold the ASCII
  833.                          string.
  834.  
  835.           Example:
  836.  
  837.           #include <scl1.h>
  838.  
  839.           #define WIDTH 7
  840.  
  841.           main()
  842.           {
  843.           long l;
  844.           char buffer[8];
  845.           int i;
  846.  
  847.           l=999999;
  848.           Cls(7,CLS_ALL);
  849.           for(i=0;i < 6;++i,l/=10)
  850.               {
  851.               WriteScreenLen(7,10,10,WIDTH,Bin2Ascii(l,buffer));
  852.               GetKey();
  853.               }
  854.           }
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.                                       Page -10-
  865.  
  866.  
  867.  
  868.  
  869.  
  870.                           SCL1 Version 2.0 Reference Manual
  871.  
  872.  
  873.                                                                         Box
  874.  
  875.           Function:    Box
  876.  
  877.           Purpose:     Draws a box with one of 12 predefined types of
  878.                        frames.  The row and column coordinates, color and
  879.                        frame type are specified.  The minimum box size is 2
  880.                        rows and 2 columns.  The function does not perform
  881.                        bound checking, the box will spill out of the screen
  882.                        area if the coordinates are outside the screen
  883.                        range.  The function draws only the box's frame and
  884.                        does not fill the box's interior.  If you desire to
  885.                        fill the box area use the GSSBox function instead. 
  886.                        If you want to draw a shadow effect, make sure to
  887.                        leave enough space outside the box area.  You can
  888.                        define other types of frames using the SetUserBox
  889.                        function.
  890.  
  891.           Declaration: void Box(int Color,int FrameType, int UpperRow,  
  892.                             int LeftCol, int LowerRow, int RightCol);
  893.  
  894.           Returns:     Nothing
  895.  
  896.           Parameters:
  897.  
  898.                  Color - color attribute for the prompt (integer).
  899.  
  900.              FrameType - frame type, an integer value from 0 to 11 as
  901.                          follows, box frame 12 selects a user defined
  902.                          frame:
  903.  
  904.                ╔═════════╗ ┌─────────┐ ╓─────────╖ ╒═════════╕  ╒════════╕
  905.                ║ FRAME 0 ║ │ FRAME 1 │ ║ FRAME 2 ║ │ FRAME 3 │  │ FRAME 4│
  906.                ╚═════════╝ └─────────┘ ╙─────────╜ ╘═════════╛  └────────┘
  907.  
  908.                            ▄▄▄▄▄▄▄▄▄▄  ░░░░░░░░░░░  ▒▒▒▒▒▒▒▒▒▒  ▓▓▓▓▓▓▓▓▓▓
  909.                  FRAME 5   ▌ FRAME 6▐  ░ FRAME 7 ░  ▒FRAME 8 ▒  ▓FRAME 9 ▓
  910.                            ▀▀▀▀▀▀▀▀▀▀  ░░░░░░░░░░░  ▒▒▒▒▒▒▒▒▒▒  ▓▓▓▓▓▓▓▓▓▓
  911.  
  912.                ██████████  **********
  913.                █FRAME 10█  *FRAME 11*
  914.                ██████████  **********
  915.  
  916.              (Note: You will not be able to print the correct frame types
  917.              if your printer does not support the IBM extended ASCII
  918.              character set.)
  919.  
  920.  
  921.  
  922.  
  923.                                       Page -11-
  924.  
  925.  
  926.  
  927.  
  928.  
  929.                           SCL1 Version 2.0 Reference Manual
  930.  
  931.  
  932.                                                                         Box
  933.  
  934.               UpperRow - upper row coordinate of the box (integer).
  935.  
  936.                LeftCol - left column coordinate of the box (integer).
  937.  
  938.               LowerRow - lower row coordinate of the box (integer).
  939.  
  940.               RightCol - right column coordinate of the box (integer).
  941.  
  942.           (Note: the home position is row 0, column 0.)
  943.  
  944.           Example:
  945.  
  946.           #include <scl1.h>
  947.           #include <scl1clor.h>
  948.  
  949.           int Color1=WHITE_BLACK;
  950.  
  951.           main()
  952.              {
  953.              Box(Color1,6,2,18,16,67);
  954.              /* Draws a box starting in line 2, column 16 and ending in
  955.                 line 18, column 67 with a small solid border.*/
  956.              }
  957.  
  958.           See also GSSBox, Shadow, SetShadowColor, SetUserFrame.
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.                                       Page -12-
  983.  
  984.  
  985.  
  986.  
  987.  
  988.                           SCL1 Version 2.0 Reference Manual
  989.  
  990.  
  991.                                                                    Buf2Disk
  992.  
  993.           Function:    Buf2Disk
  994.  
  995.           Purpose:     Saves a buffer to disk.
  996.  
  997.           Declaration: int Buf2Disk(char* Filename, char *Buffer,
  998.                            unsigned int Bytes);
  999.  
  1000.           Returns:     The return value is "0" if no error occurs or the
  1001.                        DOS error code if an error occurs.  (See Appendix
  1002.                        "A", FILE FUNCTIONS, for more information).
  1003.  
  1004.           Parameters:
  1005.  
  1006.               Filename - filename (and path if needed) of file to write
  1007.                          data to (char pointer).
  1008.  
  1009.                 Buffer - buffer that holds the data to be written to disk
  1010.                          (char pointer).
  1011.  
  1012.                  Bytes - variable that holds the number of bytes to write
  1013.                          (unsigned integer).
  1014.  
  1015.           Example:
  1016.  
  1017.           #include <scl1.h>
  1018.  
  1019.           char buffer[]="We'll write this data to disk and read it
  1020.                          back.\n";
  1021.  
  1022.           main()
  1023.              {
  1024.              int Error;
  1025.              unsigned int size;
  1026.  
  1027.              if(Error=Buf2Disk("FILE.1",buffer,sizeof(buffer)))
  1028.                 {
  1029.                 printf("Error writing file # %i\n",Error);
  1030.                 exit(-1);
  1031.                 }
  1032.              size=sizeof(buffer);
  1033.              memset(buffer,0,size);
  1034.              if(Error=File2Buf("FILE.1",buffer,&size))
  1035.                 printf("Error reading file # %i\n",Error);
  1036.              else
  1037.                 printf("%s\n",buffer);
  1038.              }
  1039.           See also File2Buf and TrapInt24.
  1040.  
  1041.                                       Page -13-
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.                           SCL1 Version 2.0 Reference Manual
  1048.  
  1049.  
  1050.                                                                    Calendar
  1051.  
  1052.           Function:    Calendar
  1053.  
  1054.           Purpose:     Displays a calendar for a given month and year. A
  1055.                        day can be displayed in a different color.  This
  1056.                        function can display the calendar either in the
  1057.                        english or spanish language. The calendar position
  1058.                        can be set to anywhere within the screen. No bounds
  1059.                        checking is made so it is important to carefully
  1060.                        calculate the display position.  This is a dialog
  1061.                        type function. Messages are defined for initializing
  1062.                        the calendar to the present system date and to
  1063.                        browse through dates using the cursor keys.
  1064.  
  1065.           Declaration: int Calendar(Message, CData *cd);
  1066.  
  1067.           Returns:     This is a dialog type function. See Appendix "E" for
  1068.                        a description of the general operation of these
  1069.                        functions. The return values are the messages
  1070.                        described in the Messages section.
  1071.  
  1072.           Parameters:
  1073.  
  1074.           The calendar information is passed in a structure type CData as
  1075.           follows:
  1076.  
  1077.           typedef struct{
  1078.              int NColor;
  1079.              int RColor;
  1080.              int Row;
  1081.              int Col;
  1082.              int FrameType;
  1083.              unsigned int *ExitKeys;
  1084.              int Lang;
  1085.              int Month;
  1086.              int Day;
  1087.              int Year;
  1088.              unsigned int EventInfo;
  1089.              }CData;
  1090.  
  1091.           where;
  1092.  
  1093.                 NColor - normal color attributes for the calendar display
  1094.                          (integer).
  1095.  
  1096.                 RColor - reversed color attributes for displaying the
  1097.                          selected day (integer).
  1098.  
  1099.  
  1100.                                       Page -14-
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.                           SCL1 Version 2.0 Reference Manual
  1107.  
  1108.  
  1109.                                                                    Calendar
  1110.  
  1111.                    Row - row position for the upper left corner of the
  1112.                          calendar (integer).
  1113.  
  1114.                    Col - column position for the upper left corner of the
  1115.                          calendar (integer).
  1116.  
  1117.              FrameType - type of frame to be used to enclose the calendar,
  1118.                          it can be any of the frame types that can be used
  1119.                          with the Box or GSSBox functions (integer).
  1120.  
  1121.               ExitKeys - an array of keys that will exit the calendar
  1122.                          function(unsigned integer).
  1123.  
  1124.                   Lang - a flag to define the language to be used when
  1125.                          displaying the calendar. To display the calendar
  1126.                          in english set Lang to "0", to display the
  1127.                          calendar in spanish set Lang to "1" (integer).
  1128.  
  1129.                  Month - the month to be displayed (integer).
  1130.  
  1131.                    Day - the day to be displayed (integer).
  1132.  
  1133.                   Year - the year to be displayed (integer).
  1134.  
  1135.              EventInfo - variable that holds the key pressed when you exit
  1136.                          the function or a non defined key is pressed
  1137.                          (unsigned integer).
  1138.  
  1139.           Messages:
  1140.  
  1141.           The following messages can be sent to Calendar:
  1142.  
  1143.                    C_INIT - initialize the CData structure to NULL and sets
  1144.                             the following default values:
  1145.  
  1146.                             NColor - set to white characters in a black
  1147.                                      background or the normal color defined
  1148.                                      by calling SetDialogColors.
  1149.  
  1150.                             HColor - set to highlighted white characters in
  1151.                                      a black background or the highlight
  1152.                                      color defined by calling
  1153.                                      SetDialogColors.
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.                                       Page -15-
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.                           SCL1 Version 2.0 Reference Manual
  1166.  
  1167.  
  1168.                                                                    Calendar
  1169.  
  1170.                                Col - set to column "24" for 80 column
  1171.                                      displays or to column "12" for 40
  1172.                                      column displays. These row positions
  1173.                                      have been selected to display the
  1174.                                      calendar in the middle of the screen.
  1175.  
  1176.                                Row - set to row "5".
  1177.  
  1178.                               Lang - set to display the calendar in
  1179.                                      english.
  1180.  
  1181.                              Month - set to the current system's month.
  1182.  
  1183.                                Day - set to the current system's day.
  1184.  
  1185.                               Year - set to the current system's year.
  1186.  
  1187.                          FrameType - set to frame type "0" (double line).
  1188.  
  1189.                           ExitKeys - defined as ENTER, ESCAPE, TAB &
  1190.                                      SHIFTAB.
  1191.  
  1192.                    C_DRAW - display the calendar with the current display
  1193.                             parameters.
  1194.  
  1195.                  C_ACTIVE - display the calendar with the current display
  1196.                             parameters and let the user change the date
  1197.                             data using the cursor movement keys as follows:
  1198.  
  1199.                          Key                      action
  1200.  
  1201.                        Up Arrow         cursor one day up.
  1202.                        Down Arrow       cursor one day down.
  1203.                        Left Arrow       cursor one day to the left.
  1204.                        Right Arrow      cursor one day to the right.
  1205.                        Page Up          increment the month by one.
  1206.                        Page Down        decrement the month by one.
  1207.                        +                increment the year by one.
  1208.                        -                decrement the year by one.
  1209.  
  1210.             C_CHECK_MOUSE - asks the function if the mouse has been clicked
  1211.                             while pointing the calendar area (while
  1212.                             currently the mouse does not affect the
  1213.                             Calendar's operation, this messages is
  1214.                             necessary when using this function as a field
  1215.                             in the Fields2 function).
  1216.  
  1217.  
  1218.                                       Page -16-
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.                           SCL1 Version 2.0 Reference Manual
  1225.  
  1226.  
  1227.                                                                    Calendar
  1228.  
  1229.               C_SHADOW_ON - displays a shadow effect the next time the
  1230.                             calendar is drawn.
  1231.  
  1232.              C_SHADOW_OFF - disables the shadow effect.
  1233.  
  1234.                   C_RESET - when this message is sent the Day, Month and
  1235.                             Year variables set to the system's date. If the
  1236.                             exit keys have not been defined they are set to
  1237.                             the default exit keys.
  1238.  
  1239.           The following messages can be returned by Calendar:
  1240.  
  1241.                      C_OK - the action requested has been performed.
  1242.  
  1243.                C_EXIT_KEY - a key that has been defined as an exit key has
  1244.                             been pressed.
  1245.  
  1246.             C_MOUSE_EVENT - the mouse has been clicked after pointing
  1247.                             outside the area defined by the function.
  1248.  
  1249.             C_ILLEGAL_KEY - a key that has not been defined has been
  1250.                             pressed.
  1251.  
  1252.            C_NEW_POSITION - this message is returned every time the month,
  1253.                             year or day has been changed.
  1254.  
  1255.                C_MY_MOUSE - this message is returned in response to the
  1256.                             C_CHECK_MOUSE message if the mouse has been
  1257.                             pressed in the Calendar screen area.
  1258.  
  1259.           Example:
  1260.  
  1261.           #include <scl1.h>
  1262.  
  1263.           main()
  1264.              {
  1265.              int Mess;                    /* returned messages         */
  1266.              CData test;                  /* define test as type CData */
  1267.  
  1268.              Calendar(C_INIT,&test);      /* Initialize to defaults    */
  1269.              Calendar(C_SHADOW_ON,&test); /* Display with shadow effect*/
  1270.              Calendar(C_DRAW,&test);      /* Display the calendar       */
  1271.              do {                         /* loop until exit key */
  1272.                 Mess=Calendar(C_ACTIVE,&test); /* browse through the
  1273.                                                   the calendar */
  1274.                 }while (Mess!=C_EXIT_KEY);
  1275.              }
  1276.  
  1277.                                       Page -17-
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.                           SCL1 Version 2.0 Reference Manual
  1284.  
  1285.  
  1286.                                                                      Center
  1287.  
  1288.           Function:    Center
  1289.  
  1290.           Purpose:     Centers a string horizontally.
  1291.  
  1292.           Declaration: int Center(char *String);
  1293.  
  1294.           Returns:     Returns the column position required for displaying
  1295.                        the string centered in the screen.
  1296.  
  1297.           Parameters:
  1298.  
  1299.              String -  pointer to the string to be centered (char).
  1300.  
  1301.           Example:
  1302.  
  1303.           #include <slc1.h>
  1304.           #include <scl1clor.h>
  1305.  
  1306.           int Color1=WHITE_BLACK;
  1307.           char Txt[10]="Main Menu";
  1308.  
  1309.           main()
  1310.              {
  1311.              int Column;
  1312.  
  1313.              Column=Center(Txt);
  1314.              WriteString(Color1,1,Column,Txt);
  1315.              }
  1316.  
  1317.           or
  1318.  
  1319.           main()
  1320.              {
  1321.              WriteString(Color1,1,Center(Txt),Txt);
  1322.              }
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.                                       Page -18-
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.                           SCL1 Version 2.0 Reference Manual
  1343.  
  1344.  
  1345.                                                             ChangeDumpColor
  1346.  
  1347.           Function:    ChangeDumpColor
  1348.  
  1349.           Purpose:     Changes the color attributes of a ScreenDump array
  1350.                        (See ScreenDump).
  1351.  
  1352.           Declaration: void ChangeDumpColor(int OldColor, int NewColor,
  1353.                             char*Array);
  1354.  
  1355.           Returns:     Nothing
  1356.  
  1357.           Parameters:
  1358.  
  1359.               OldColor - color value you want to change (integer).
  1360.  
  1361.               NewColor - new color you desire (integer).
  1362.  
  1363.                 *Array - ScreenDump array (char pointer).
  1364.  
  1365.           Example:
  1366.  
  1367.           #include <scl1.h>
  1368.  
  1369.           char Array[]={'A',7,'B',0x70,\n,'C',0x70,'D',7,0};
  1370.  
  1371.           main()
  1372.              {
  1373.  
  1374.              /* Each character is followed by its color attribute, a \n can
  1375.                 be used to indicate end of lines and a "0" must be used to
  1376.                 indicate the end of the array */
  1377.  
  1378.                 ScreenDump(10,10,Array); /* Write at line 10, column 10 */
  1379.                 GetKey();
  1380.  
  1381.                 ChangeDumpColor(0x70,7,Array);
  1382.                 ScreenDump(10,10,Array); /* Write at line 10, column 10 */
  1383.                 /* Change all character attributes 0x17 to 7 */
  1384.              }
  1385.  
  1386.           See also ScreenDump.
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.                                       Page -19-
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.                           SCL1 Version 2.0 Reference Manual
  1402.  
  1403.  
  1404.                                                             ChangeExtension
  1405.  
  1406.           Function:    ChangeExtension
  1407.  
  1408.           Purpose:     Changes a filename's extension or adds an extension
  1409.                        if it does not has one.
  1410.  
  1411.           Declaration: char *ChangeExtension(char *Filename,
  1412.                             char *Extension);
  1413.  
  1414.           Returns:     The return value is a pointer to the filename
  1415.                        buffer.
  1416.  
  1417.           Parameters:
  1418.  
  1419.               Filename - filename to change its extension (char pointer).
  1420.  
  1421.              Extension - new extension (char pointer).
  1422.  
  1423.           Example:
  1424.  
  1425.           #include <scl1.h>
  1426.  
  1427.           char Buffer[]="MYFILE.TXT";
  1428.  
  1429.           main()
  1430.              {
  1431.              printf("%s\n",Buffer);
  1432.              ChangeExtension(Buffer,".BAK");
  1433.  
  1434.              /* Change extension from ".TXT" to ".BAK"*/
  1435.  
  1436.              printf("%s\n",Buffer);
  1437.              }
  1438.  
  1439.           See also AddExtension and RemoveExtension
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.                                       Page -20-
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.                           SCL1 Version 2.0 Reference Manual
  1461.  
  1462.  
  1463.                                                                CheckBarMenu
  1464.  
  1465.           Function:    CheckBarMenu  (OBSOLETE, use the MenuSystem
  1466.                                      function, this function will
  1467.                                      eventually be removed from future
  1468.                                      versions of SCL1.)
  1469.  
  1470.           Purpose:     Determines the number of the item selected with the
  1471.                        mouse in a bar menu.
  1472.  
  1473.           Declaration: int CheckBarMenu(int Number, struct BarMenu *bm);
  1474.  
  1475.           Returns:     The return value is the Selection number ( > "1") or
  1476.                        "0" if none has been selected.
  1477.  
  1478.           Parameters:
  1479.  
  1480.           The BarMenu information must be given as an array of structures
  1481.           as follows:
  1482.  
  1483.              struct BarMenu{
  1484.                 int StartCol,EndCol;
  1485.                 char String[20];
  1486.                 };
  1487.  
  1488.           where,
  1489.  
  1490.               StartCol - column position where to start displaying the menu
  1491.                          item information (integer).
  1492.  
  1493.                 EndCol - column position where to end displaying the menu
  1494.                          item information (integer).
  1495.  
  1496.                 String - menu item information (char pointer).
  1497.  
  1498.           The parameters passed to the function are:
  1499.  
  1500.                 Number - number of menu options (integer).
  1501.  
  1502.                BarMenu - pointer to the BarMenu structure.
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.                                       Page -21-
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.                           SCL1 Version 2.0 Reference Manual
  1520.  
  1521.  
  1522.                                                                CheckBarMenu
  1523.  
  1524.           Example:
  1525.  
  1526.           #include <scl1.h>
  1527.           #include <scl1clor.h>
  1528.  
  1529.           /* Bar Menu structure */
  1530.  
  1531.           struct BarMenu bm[]={
  1532.              2,8,              /*Start and end of display*/
  1533.              "Option1",        /*Menu item information   */
  1534.              15,21,            /* Second menu option     */
  1535.              "Option2"};
  1536.  
  1537.           main()
  1538.              {
  1539.              int Selection=0;
  1540.  
  1541.              if(CheckMouse())
  1542.                 InitMouse(IM_SHOW);
  1543.              else
  1544.                 printf("No Mouse available\n");
  1545.              DrawBarMenu(BLACK_WHITE,WHITE_BLACK,2,Selection,bm);
  1546.              while(Selection==0)
  1547.                 {
  1548.                 if((Selection=CheckBarMenu(2,bm)))  /* Selection made? */
  1549.                    DrawBarMenu(BLACK_WHITE,WHITE_BLACK,2,Selection,bm);
  1550.                 }
  1551.              }
  1552.  
  1553.           NOTE: Use DrawBarMenu to draw bar menus.
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.                                       Page -22-
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.                           SCL1 Version 2.0 Reference Manual
  1579.  
  1580.  
  1581.                                                                   CheckChar
  1582.  
  1583.           Function:    CheckChar
  1584.  
  1585.           Purpose:     Checks for a valid keyboard character.
  1586.  
  1587.           Declaration: unsigned int CheckChar(unsigned int Character,
  1588.                                     unsigned int ControlCode);
  1589.  
  1590.           Returns:     The return value is the character, if valid, or "0"
  1591.                        if the character is not valid.
  1592.  
  1593.           Parameters:
  1594.  
  1595.              character - character to verify (unsigned integer).
  1596.  
  1597.            ControlCode - type of character to accept (unsigned integer).
  1598.  
  1599.                 Control codes defined in SCL1.H:
  1600.  
  1601.                    CC_ANY - accept any character.
  1602.                 CC_LETTER - only letters.
  1603.                  CC_DIGIT - only digits.
  1604.             CC_CAPITALIZE - capitalize.
  1605.                   CC_REAL - accept real numbers.
  1606.               CC_FILESPEC - accept valid filename characters
  1607.                CC_ESPANOL - letters & accented characters used in the
  1608.                             spanish language.
  1609.            CC_PUNCTUATION - accept (,;.+-* spaces,etc.)
  1610.                   CC_PATH - accept valid filenames and pathnames
  1611.                             characters.
  1612.                 CC_SEARCH - accept all characters of CC_PATH and the "*"
  1613.                             and "?" characters.
  1614.            CC_EXPONENTIAL - accept numbers in exponential form.
  1615.  
  1616.           Example:
  1617.  
  1618.           #include<scl1.h>
  1619.           #include<scl1keys.h>
  1620.  
  1621.           main()
  1622.              {
  1623.              unsigned int Key;
  1624.              Key=GetKey();
  1625.              if (CheckChar(Key,CC_LETTER))>0)
  1626.                    /* Character is valid */
  1627.              else
  1628.                    /* Character is invalid */
  1629.              }
  1630.  
  1631.                                       Page -23-
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.                           SCL1 Version 2.0 Reference Manual
  1638.  
  1639.  
  1640.                                                               CheckItemList
  1641.  
  1642.           Function:    CheckItemList
  1643.  
  1644.           Purpose:     Checks if the mouse has been clicked at any item in
  1645.                        an item list (see DrawItemList).
  1646.  
  1647.           Declaration: int CheckItemList(int Number, int ItemLength,
  1648.                            struct ItemList *il);
  1649.  
  1650.           Returns:     The return value is the number of the item selected
  1651.                        with the mouse (>"1") or "0" if none has been
  1652.                        selected.
  1653.  
  1654.           Parameters:
  1655.  
  1656.           The item list information must be given as an array of structures
  1657.           as follows:
  1658.  
  1659.              struct ItemList{
  1660.                 int Row,Col;
  1661.                 char *String;
  1662.                 };
  1663.  
  1664.           where,
  1665.  
  1666.                    Row - row position of the item (integer).
  1667.  
  1668.                    Col - column position of the item (integer).
  1669.  
  1670.                 String - char pointer to item text.
  1671.  
  1672.           The parameters passed to the function are:
  1673.  
  1674.                 Number - number of items (integer).
  1675.  
  1676.             ItemLength - maximum length of items (integer).
  1677.  
  1678.               ItemList - pointer to the defined structure.
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.                                       Page -24-
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.                           SCL1 Version 2.0 Reference Manual
  1697.  
  1698.  
  1699.                                                               CheckItemList
  1700.  
  1701.           Example:
  1702.  
  1703.           #include <scl1.h>
  1704.           #include <scl1clor.h>
  1705.  
  1706.           struct ItemList il[]={
  1707.              10,10,"String 1",
  1708.              10,30,"String 2",
  1709.              10,50,"String 3",
  1710.              };
  1711.  
  1712.           main()
  1713.              {
  1714.              int Selection=0;
  1715.  
  1716.              Cls(WHITE_BLACK,CLS_ALL);
  1717.              if(CheckMouse())
  1718.                 InitMouse(IM_SHOW);
  1719.              else
  1720.                 printf("No Mouse available\n");
  1721.              DrawItemList(WHITE_BLACK,BLACK_WHITE,3,Selection,il);
  1722.              while(Selection==0)
  1723.                 {
  1724.                 if(Selection=CheckItemList(3,8,il))
  1725.                    DrawItemList(WHITE_BLACK,BLACK_WHITE,3,Selection,il);
  1726.                 }
  1727.              }
  1728.  
  1729.           NOTE: Use DrawItemList to draw an ItemList structure to the
  1730.                 screen.  See also ListManager to integrate mouse and
  1731.                 keyboard.  The Dialog type function ListWindow provides an
  1732.                 alternative way to perform the same task.
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738.  
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.                                       Page -25-
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.                           SCL1 Version 2.0 Reference Manual
  1756.  
  1757.  
  1758.                                                                  CheckMouse
  1759.  
  1760.           Function:    CheckMouse
  1761.  
  1762.           Purpose:     Determines if a mouse is installed.  Sets variable
  1763.                        MSE_MouseFl to "1" if mouse is found.
  1764.  
  1765.           Declaration: int CheckMouse(void);
  1766.  
  1767.           Returns:     The return value of "1" if the mouse is installed
  1768.                        and "0" if no mouse is installed.
  1769.  
  1770.           Parameters:  None
  1771.  
  1772.           Example:
  1773.  
  1774.           #include <scl1.h>
  1775.  
  1776.           main()
  1777.              {
  1778.  
  1779.              /* do we have a mouse? */
  1780.              if(CheckMouse())
  1781.                 {
  1782.                 /* Yes */
  1783.                 ResetMouse();  /* reset mouse */
  1784.                 SetMouseIsr(); /* initialize ISR */
  1785.                 ShowMouse();   /* cursor on */
  1786.                 }
  1787.              .
  1788.              .
  1789.              .
  1790.              ResetMouse();  /* reset mouse before exit */
  1791.              }
  1792.  
  1793.  
  1794.  
  1795.  
  1796.  
  1797.  
  1798.  
  1799.  
  1800.  
  1801.  
  1802.  
  1803.  
  1804.  
  1805.  
  1806.  
  1807.  
  1808.                                       Page -26-
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.                           SCL1 Version 2.0 Reference Manual
  1815.  
  1816.  
  1817.                                                            CheckMouseButton
  1818.  
  1819.           Function:    CheckMouseButton
  1820.  
  1821.           Purpose:     Checks if the mouse has been clicked at any screen
  1822.                        mouse button.
  1823.  
  1824.           Declaration: int CheckMouseButton(int Number,
  1825.                             struct MouseButton *p);
  1826.  
  1827.           Returns:     The return value is the number of the selected
  1828.                        screen Mouse Button or "0" if none has been
  1829.                        selected.
  1830.  
  1831.           Parameters:
  1832.  
  1833.           The Mouse Button information must be given in a structure as
  1834.           follows:
  1835.  
  1836.                 struct MouseButton{
  1837.                    int Top,Left,Bottom,Right;
  1838.                    int Row,Col;
  1839.                    char String[20];
  1840.                    };
  1841.  
  1842.           where,
  1843.  
  1844.                     Top -   upper line coordinate of the Mouse Button area
  1845.                             (integer).
  1846.  
  1847.                    Left -   upper column coordinate of the Mouse Button
  1848.                             area (integer).
  1849.  
  1850.                  Bottom -   right row coordinate of the Mouse Button area
  1851.                             (integer).
  1852.  
  1853.                   Right -   right column coordinate of the Mouse Button
  1854.                             area (integer).
  1855.  
  1856.                     Row -   row coordinate of the Mouse Button text
  1857.                             (integer).
  1858.  
  1859.                     Col -   column coordinate of the Mouse Button text
  1860.                             (integer).
  1861.  
  1862.                  String -   Mouse Button text (maximum of 19 characters.).
  1863.  
  1864.  
  1865.  
  1866.  
  1867.                                       Page -27-
  1868.  
  1869.  
  1870.  
  1871.  
  1872.  
  1873.                           SCL1 Version 2.0 Reference Manual
  1874.  
  1875.  
  1876.                                                            CheckMouseButton
  1877.  
  1878.           The parameters passed to the function are:
  1879.  
  1880.                  Number -   number of mouse buttons (integer).
  1881.  
  1882.               MouseButton - pointer to defined structure.
  1883.  
  1884.           Example:
  1885.  
  1886.           struct MouseButton mb[]={
  1887.              4,35,6,45,  /* Box coordinates */
  1888.              5,38,       /* String position */
  1889.              "Yes",      /* String */
  1890.  
  1891.              10,35,12,45,
  1892.              11,39,
  1893.              "No",
  1894.              };
  1895.  
  1896.           /* Call CheckMouseButton(Number of options, pointer to the
  1897.              structure). */
  1898.  
  1899.              if((Selection=CheckMouseButton(2,mb))) /* Bigger than 1? */
  1900.                 {                    /* Selection was made */
  1901.                 switch(Selection)
  1902.                    {
  1903.                    case 1:
  1904.                        .
  1905.                        .
  1906.                    case 2:
  1907.                        .
  1908.                        .
  1909.  
  1910.           See also DrawMouseButton to draw the buttons.
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.  
  1922.  
  1923.  
  1924.  
  1925.  
  1926.                                       Page -28-
  1927.  
  1928.  
  1929.  
  1930.  
  1931.  
  1932.                           SCL1 Version 2.0 Reference Manual
  1933.  
  1934.  
  1935.                                                                 ClearKeyBuf
  1936.  
  1937.           Function:    ClearKeyBuf
  1938.  
  1939.           Purpose:     Clears keyboard buffer of any character or keystroke
  1940.                        pending to be processed.
  1941.  
  1942.           Declaration: void ClearKeyBuf(void);
  1943.  
  1944.           Returns:     Nothing.
  1945.  
  1946.           Parameters:  None.
  1947.  
  1948.           Example:
  1949.  
  1950.           #include <slc1.h>
  1951.  
  1952.           main()
  1953.              {
  1954.              ClearKeyBuf();
  1955.              }
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.                                       Page -29-
  1986.  
  1987.  
  1988.  
  1989.  
  1990.  
  1991.                           SCL1 Version 2.0 Reference Manual
  1992.  
  1993.  
  1994.                                                                   CloseFile
  1995.  
  1996.           Function:    CloseFile
  1997.  
  1998.           Purpose:     Closes a file.
  1999.  
  2000.           Declaration: int CloseFile(int Handle);
  2001.  
  2002.           Returns:     The return value is "0" if no error occurs or the
  2003.                        DOS error code if an error occurs.  (See Appendix
  2004.                        "A", FILE FUNCTIONS, for more information).
  2005.  
  2006.           Parameters:
  2007.  
  2008.                 Handle - Handle number is given by DOS when you create or
  2009.                          open a file (integer).
  2010.  
  2011.           Example:
  2012.  
  2013.           #include <scl1.h>
  2014.           /* This is the source code of the Buf2Disk function */
  2015.  
  2016.           Buf2Disk(char *Filename,char *Buffer,unsigned int Bytes)
  2017.              {
  2018.              int i,handle;
  2019.  
  2020.              if(i=CreateFile(Filename,&handle,F_ARCHIVE))
  2021.                 return(i);
  2022.  
  2023.              if(i=WriteFile(handle,Buffer,Bytes))
  2024.                 {
  2025.                 if(i > 0)
  2026.                    CloseFile(handle);
  2027.                 return(i);
  2028.                 }
  2029.              return(CloseFile(handle));
  2030.              }
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.                                       Page -30-
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.                           SCL1 Version 2.0 Reference Manual
  2051.  
  2052.  
  2053.                                                                         Cls
  2054.  
  2055.           Function:    Cls
  2056.  
  2057.           Purpose:     Clears a screen area.
  2058.  
  2059.           Declaration: void Cls(int Color,int UpperRow,int LeftCol,
  2060.                             int BottomRow, int RightCol);
  2061.  
  2062.           Returns:     Nothing
  2063.  
  2064.           Parameters:
  2065.  
  2066.                  Color - color attribute of the area to be cleared
  2067.                          (integer).
  2068.  
  2069.               UpperRow - upper row coordinate of the area to be cleared
  2070.                          (integer).
  2071.  
  2072.                LeftCol - left column coordinate of the area to be cleared
  2073.                          (integer).
  2074.  
  2075.               LowerRow - lower row coordinate of the area to be cleared.
  2076.                          (integer).
  2077.  
  2078.               RightCol - right column coordinate of the area to be
  2079.                          cleared.(integer).
  2080.  
  2081.           (Note: the top left position is 0, column 0.)
  2082.  
  2083.           Example:
  2084.  
  2085.           #include <scl1.h>
  2086.           #include <scl1clor.h>
  2087.  
  2088.           int Color1=WHITE_BLACK;
  2089.  
  2090.           main()
  2091.              {
  2092.              Cls(Color1,18,0,24,79);
  2093.              }
  2094.  
  2095.           or,
  2096.  
  2097.           main()
  2098.              {
  2099.              Cls(Color1,CLS_ALL); (CLS_ALL is defined in SCL1.H to clear
  2100.                                   the whole screen.)
  2101.              }
  2102.  
  2103.                                       Page -31-
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.                           SCL1 Version 2.0 Reference Manual
  2110.  
  2111.  
  2112.                                                                  CreateFile
  2113.  
  2114.           Function:    CreateFile
  2115.  
  2116.           Purpose:     Creates a new file or truncates an existing file to
  2117.                        zero.
  2118.  
  2119.           Declaration: int CreateFile(char *Filename,int *Handle,
  2120.                            int Attrib);
  2121.  
  2122.           Returns:     The return value is "0" if no error occurs or the
  2123.                        DOS error code if an error occurs.  (See Appendix
  2124.                        "A", FILE FUNCTIONS, for more information).
  2125.  
  2126.           Parameters:
  2127.  
  2128.               Filename - char pointer to a valid filename.
  2129.  
  2130.                 Handle - pointer to an integer variable that contains the
  2131.                          file handle number given by DOS (integer).
  2132.  
  2133.                 Attrib - type of file to create, Read only, hidden, etc.
  2134.                          (integer). The following types has been defined in
  2135.                          SCL1.H:
  2136.  
  2137.                          F_READ_ONLY, F_HIDDEN, F_SYSTEM, F_VOLUME,
  2138.                          F_DIRECTORY, F_ARCHIVE
  2139.  
  2140.           Example:
  2141.  
  2142.           #include <scl1.h>
  2143.           /* This is the source code of the Buf2Disk function */
  2144.  
  2145.           Buf2Disk(char *Filename,char *Buffer,unsigned int Bytes)
  2146.              {
  2147.              int i,handle;
  2148.  
  2149.              if(i=CreateFile(Filename,&handle,F_ARCHIVE))
  2150.                 return(i);
  2151.  
  2152.              if(i=WriteFile(handle,Buffer,Bytes))
  2153.                 {
  2154.                 if(i > 0)
  2155.                    CloseFile(handle);
  2156.                 return(i);
  2157.                 }
  2158.              return(CloseFile(handle));
  2159.              }
  2160.  
  2161.  
  2162.                                       Page -32-
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.                           SCL1 Version 2.0 Reference Manual
  2169.  
  2170.  
  2171.                                                                   CursorOff
  2172.                                                                    CursorOn
  2173.  
  2174.           Function:    CursorOff
  2175.                        CursorOn
  2176.  
  2177.           Purpose:     Turns the cursor off (cursor not visible), or on
  2178.                        (cursor visible).
  2179.  
  2180.           Declaration: void CursorOff(void);
  2181.                        void CursorOn(void);
  2182.  
  2183.           Returns:     Nothing
  2184.  
  2185.           Parameters:  None
  2186.  
  2187.           Example:
  2188.  
  2189.  
  2190.           #include <scl1.h>
  2191.  
  2192.           main()
  2193.              {
  2194.              CursorOff();
  2195.              printf("Press any key to turm cursor on\n");
  2196.              GetKey();
  2197.              CursorOn();
  2198.              }
  2199.  
  2200.  
  2201.  
  2202.  
  2203.  
  2204.  
  2205.  
  2206.  
  2207.  
  2208.  
  2209.  
  2210.  
  2211.  
  2212.  
  2213.  
  2214.  
  2215.  
  2216.  
  2217.  
  2218.  
  2219.  
  2220.  
  2221.                                       Page -33-
  2222.  
  2223.  
  2224.  
  2225.  
  2226.  
  2227.                           SCL1 Version 2.0 Reference Manual
  2228.  
  2229.  
  2230.                                                                  DeleteFile
  2231.  
  2232.           Function:    DeleteFile
  2233.  
  2234.           Purpose:     Deletes a file.
  2235.  
  2236.           Declaration: int DeleteFile(char *Filename);
  2237.  
  2238.           Returns:     The return value is "0" if no error occurs or the
  2239.                        DOS error code if an error occurs.  (See Appendix
  2240.                        "A", FILE FUNCTIONS, for more information).
  2241.  
  2242.           Parameters:
  2243.  
  2244.               Filename - char pointer to a valid filename.
  2245.  
  2246.           Example:
  2247.  
  2248.           #include <slc1.h>
  2249.  
  2250.           main()
  2251.              {
  2252.              int RetCode;
  2253.              RetCode=DeleteFile("c:\\bin\\file.1");
  2254.              /* Will delete file "FILE.1" stored in drive "C" and the
  2255.                 "BIN" directory.  Note the double backslashes between
  2256.                 the elements of the pathname. */
  2257.              }
  2258.  
  2259.  
  2260.  
  2261.  
  2262.  
  2263.  
  2264.  
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.  
  2271.  
  2272.  
  2273.  
  2274.  
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280.                                       Page -34-
  2281.  
  2282.  
  2283.  
  2284.  
  2285.  
  2286.                           SCL1 Version 2.0 Reference Manual
  2287.  
  2288.  
  2289.                                                                   DialogBox
  2290.  
  2291.           Function:    DialogBox
  2292.  
  2293.           Purpose:     Displays a dialog box for keyboard input. The box
  2294.                        will be displayed at the screen's center.  The
  2295.                        function takes care or saving and restoring the
  2296.                        screen contents of the display area.  See the
  2297.                        GetString function for the editing features.
  2298.  
  2299.           Declaration: int DialogBox(int BoxColor, char *Prompt,
  2300.                            int InputColor, int MaxChar,
  2301.                            unsigned int CharType, char *Buffer);
  2302.  
  2303.           Returns:     The return value is the number of characters typed
  2304.                        or "-1" if Esc is pressed.
  2305.  
  2306.           Parameters:
  2307.  
  2308.               BoxColor - color attributes of the dialog box (integer).
  2309.  
  2310.                 Prompt - pointer to the dialog prompt (char).
  2311.  
  2312.             InputColor - color attributes of the input (integer).
  2313.  
  2314.                MaxChar - maximum number of characters to accept (integer).
  2315.  
  2316.               CharType - the type of characters to accept as defined in
  2317.                          SCL1.H (refer to the CheckChar function) (unsigned
  2318.                          integer).
  2319.  
  2320.                 Buffer - pointer to the buffer to be used to store the
  2321.                          information entered, it must be one digit larger
  2322.                          than the field size (for the string termination
  2323.                          null character).
  2324.  
  2325.           Example:
  2326.  
  2327.           #include <scl1.h>
  2328.           #include <scl1clor.h>
  2329.  
  2330.           int Color1=WHITE_BLACK+HIGHLIGHT;
  2331.           int Color2=BLACK_WHITE;
  2332.           char buffer[33]         /* buffer to hold input, one character
  2333.                                      larger than MaxChar */
  2334.           main()
  2335.              {
  2336.              DialogBox(Color1,"Filename",Color2,32,CC_FILESPEC,buffer);
  2337.              }
  2338.  
  2339.                                       Page -35-
  2340.  
  2341.  
  2342.  
  2343.  
  2344.  
  2345.                           SCL1 Version 2.0 Reference Manual
  2346.  
  2347.  
  2348.                                                                DisableMouse
  2349.  
  2350.           Function:    DisableMouse
  2351.  
  2352.           Purpose:     Removes interrupt service routine installed by
  2353.                        SetMouseIsr
  2354.  
  2355.           Declaration: void DisableMouse(void);
  2356.  
  2357.           Returns:     Nothing
  2358.  
  2359.           Parameters:  None
  2360.  
  2361.           Example:
  2362.  
  2363.           #include <scl1.h>
  2364.  
  2365.           main()
  2366.              {
  2367.              if(CheckMouse();
  2368.                 {
  2369.                 ResetMouse();
  2370.                 SetMouseIsr();
  2371.                 ShowMouse();
  2372.                 }
  2373.              .
  2374.              .
  2375.              .
  2376.              DisableMouse();
  2377.              }
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.  
  2384.  
  2385.  
  2386.  
  2387.  
  2388.  
  2389.  
  2390.  
  2391.  
  2392.  
  2393.  
  2394.  
  2395.  
  2396.  
  2397.  
  2398.                                       Page -36-
  2399.  
  2400.  
  2401.  
  2402.  
  2403.  
  2404.                           SCL1 Version 2.0 Reference Manual
  2405.  
  2406.  
  2407.                                                                 DrawBarMenu
  2408.  
  2409.           Function:    DrawBarMenu   (OBSOLETE, use the MenuSystem
  2410.                                      function, this function will
  2411.                                      eventually be removed from future
  2412.                                      versions of SCL1.)
  2413.  
  2414.           Purpose:     Draws a Bar Menu to the screen's top line.
  2415.  
  2416.           Declaration: void DrawBarMenu(int NormalColor,int SelectedColor,
  2417.                             int NumItems,int Selection,struct BarMenu* bm);
  2418.  
  2419.           Returns:     Nothing
  2420.  
  2421.           Parameters:
  2422.  
  2423.           The Menu information must be given as an array of structures as
  2424.           follows:
  2425.  
  2426.              struct BarMenu{
  2427.                 int StartCol,EndCol;
  2428.                 char String[20];
  2429.                 };
  2430.  
  2431.           where,
  2432.  
  2433.               StartCol - column position of the start of the prompt
  2434.                          (integer).
  2435.  
  2436.                 EndCol - column position of the end of the prompt
  2437.                          (integer).
  2438.  
  2439.                 String - char pointer to prompt.
  2440.  
  2441.           The parameters passed to the function are:
  2442.  
  2443.                 NColor - normal color attributes of menu (integer).
  2444.  
  2445.                 RColor - reversed color attributes of menu (integer).
  2446.  
  2447.               NumItems - number of menu items (integer).
  2448.  
  2449.              Selection - default selection (integer).
  2450.  
  2451.                BarMenu - pointer to a previously defined BarMenu structure.
  2452.  
  2453.  
  2454.  
  2455.  
  2456.  
  2457.                                       Page -37-
  2458.  
  2459.  
  2460.  
  2461.  
  2462.  
  2463.                           SCL1 Version 2.0 Reference Manual
  2464.  
  2465.  
  2466.                                                                 DrawBarMenu
  2467.  
  2468.           Example:
  2469.  
  2470.           #include <scl1.h>
  2471.           #include <scl1clor.h>
  2472.  
  2473.           /* Bar Menu structure */
  2474.  
  2475.           struct BarMenu bm[]={
  2476.              2,8,              /*Start and end of display*/
  2477.              "Option1",        /*Menu item information   */
  2478.              15,21,            /* Second menu option     */
  2479.              "Option2"};
  2480.  
  2481.           main()
  2482.              {
  2483.              int Selection=0;
  2484.  
  2485.              if(CheckMouse())
  2486.                 InitMouse(IM_SHOW);
  2487.              else
  2488.                 printf("No Mouse available\n");
  2489.              DrawBarMenu(BLACK_WHITE,WHITE_BLACK,2,Selection,bm);
  2490.              while(Selection==0)
  2491.                 {
  2492.                 if((Selection=CheckBarMenu(2,bm)))  /* Selection made? */
  2493.                    DrawBarMenu(BLACK_WHITE,WHITE_BLACK,2,Selection,bm);
  2494.                 }
  2495.              }
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.  
  2503.  
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.  
  2516.                                       Page -38-
  2517.  
  2518.  
  2519.  
  2520.  
  2521.  
  2522.                           SCL1 Version 2.0 Reference Manual
  2523.  
  2524.  
  2525.                                                                 DrawBoxLine
  2526.  
  2527.           Function:    DrawBoxLine
  2528.  
  2529.           Purpose:     Draws either vertical or horizontal lines inside a
  2530.                        box with the proper end line characters.
  2531.  
  2532.           Declaration: void DrawBoxLine(int Color,int FrameType,int Row1,
  2533.                             int Col1,int Row2,int Col2);
  2534.  
  2535.           Returns:     Nothing
  2536.  
  2537.           Parameters:
  2538.  
  2539.           The parameters passed to the function are:
  2540.  
  2541.                  Color - color attributes of the line to be drawn
  2542.                          (integer).
  2543.  
  2544.              FrameType - type of frame used to draw the box (integer).
  2545.  
  2546.                   Row1 - row position where the line starts (integer).
  2547.  
  2548.                   Col1 - column position where the line starts (integer).
  2549.  
  2550.                   Row2 - row position where the line ends (integer).
  2551.  
  2552.                   Col2 - column position where the line ends (integer).
  2553.  
  2554.              Note: To draw horizontal lines both Row1 and Row2 must have
  2555.                    the same value, for vertical lines both Col1 and Col2
  2556.                    must have the same value.
  2557.  
  2558.           Example:
  2559.  
  2560.           #include <scl1.h>
  2561.           #include <scl1clor.h>
  2562.  
  2563.           int Color1=WHITE_BLACK;
  2564.  
  2565.           main()
  2566.              {
  2567.              Box(Color1,0,0,0,24,79);         /* Full screen box */
  2568.              DrawBoxLine(Color1,0,5,0,5,79);  /* Horizontal line in row 5*/
  2569.              DrawBoxLine(Color1,0,5,39,24,39);/* Vertical line between rows
  2570.                                                  5 and 24 */
  2571.              }
  2572.  
  2573.           See also Box, GSSBox, DrawLine
  2574.  
  2575.                                       Page -39-
  2576.  
  2577.  
  2578.  
  2579.  
  2580.  
  2581.                           SCL1 Version 2.0 Reference Manual
  2582.  
  2583.  
  2584.                                                                DrawItemList
  2585.  
  2586.           Function:    DrawItemList
  2587.  
  2588.           Purpose:     Draws a list of items (strings) to the screen and
  2589.                        permits the user to browse through them.  The
  2590.                        selected item (>"0") is drawn in the color specified
  2591.                        with SelectedColor.
  2592.  
  2593.           Declaration: void DrawItemList(int NormalColor,
  2594.                             int SelectedColor, int Number, int Selection,
  2595.                             Struct ItemList *il);
  2596.  
  2597.           Returns:     Nothing
  2598.  
  2599.           Parameters:
  2600.  
  2601.           The ItemList information must be given as an array of structures
  2602.           as follows:
  2603.  
  2604.              struct ItemList{
  2605.                 int Row,Col;
  2606.                 char *String;
  2607.                 };
  2608.  
  2609.           where,
  2610.  
  2611.                       Row - row position of the item (integer).
  2612.  
  2613.                       Col - column position of the item (integer).
  2614.  
  2615.                    String - char pointer to item text.
  2616.  
  2617.           The parameters passed to the function are:
  2618.  
  2619.               NormalColor - color attributes for the normal display of
  2620.                             items (integer).
  2621.  
  2622.             SelectedColor - color attributes for the display of the
  2623.                             selected item (integer).
  2624.  
  2625.                    Number - number of items to be displayed (integer).
  2626.  
  2627.                 Selection - default selection to be displayed when entering
  2628.                             the function (integer).
  2629.  
  2630.                  ItemList - pointer to a previously defined ItemList
  2631.                             structure.
  2632.  
  2633.  
  2634.                                       Page -40-
  2635.  
  2636.  
  2637.  
  2638.  
  2639.  
  2640.                           SCL1 Version 2.0 Reference Manual
  2641.  
  2642.  
  2643.                                                                DrawItemList
  2644.  
  2645.           Example:
  2646.  
  2647.           #include <scl1.h>
  2648.           #include <scl1clor.h>
  2649.  
  2650.           struct ItemList il[]={
  2651.              10,10,"String 1",
  2652.              10,30,"String 2",
  2653.              10,50,"String 3",
  2654.              };
  2655.  
  2656.           main()
  2657.              {
  2658.              int Selection=0;
  2659.  
  2660.              Cls(WHITE_BLACK,CLS_ALL);
  2661.              if(CheckMouse())
  2662.                 InitMouse(IM_SHOW);
  2663.              else
  2664.                 printf("No Mouse available\n");
  2665.              DrawItemList(WHITE_BLACK,BLACK_WHITE,3,Selection,il);
  2666.              while(Selection==0)
  2667.                 {
  2668.                 if(Selection=CheckItemList(3,8,il))
  2669.                    DrawItemList(WHITE_BLACK,BLACK_WHITE,3,Selection,il);
  2670.                 }
  2671.              }
  2672.  
  2673.           NOTE: The ScrollWindow and ListWindow functions provide
  2674.                 alternatives to perform the same tasks.
  2675.  
  2676.  
  2677.  
  2678.  
  2679.  
  2680.  
  2681.  
  2682.  
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.                                       Page -41-
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.                           SCL1 Version 2.0 Reference Manual
  2700.  
  2701.  
  2702.                                                                    DrawLine
  2703.  
  2704.           Function:    DrawLine
  2705.  
  2706.           Purpose:     Draws either vertical or horizontal lines.
  2707.  
  2708.           Declaration: void DrawLine(int Color, int Row, int Col,
  2709.                             int Count, int Direction, int Character);
  2710.  
  2711.           Returns:     Nothing
  2712.  
  2713.           Parameters:
  2714.  
  2715.           The parameters passed to the function are:
  2716.  
  2717.                  Color - color attributes of the line to be drawn
  2718.                          (integer).
  2719.  
  2720.                    Row - row position where the line starts (integer).
  2721.  
  2722.                    Col - column position where the line starts (integer).
  2723.  
  2724.                  Count - number of line characters to be drawn (integer).
  2725.  
  2726.              Direction - direction to draw. Variables DL_HORIZONTAL and
  2727.                          DL_VERTICAL has been defined in SCL1.H.
  2728.  
  2729.              Character - graphic character to use for line drawing
  2730.                          (integer).
  2731.  
  2732.           Example:
  2733.  
  2734.           #include <scl1.h>
  2735.           #include <scl1clor.h>
  2736.  
  2737.           int Color1=WHITE_BLACK;
  2738.  
  2739.           main()
  2740.              {
  2741.              DrawLine(Color1,5,5,10,DL_HORIZONTAL,196);
  2742.              /* Horizontal line in row 5, between columns 5 and 15 */
  2743.  
  2744.              DrawLine(Color1,5,5,14,DL_VERTICAL,179);
  2745.              /* Vertical line between rows 5 and 19, column 5 */
  2746.              }
  2747.  
  2748.  
  2749.  
  2750.  
  2751.  
  2752.                                       Page -42-
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.                           SCL1 Version 2.0 Reference Manual
  2759.  
  2760.  
  2761.                                                             DrawMouseButton
  2762.  
  2763.           Function:    DrawMouseButton
  2764.  
  2765.           Purpose:     Draws one or more mouse buttons to the screen. The
  2766.                        selected button is drawn in the specified color with
  2767.                        a double line box.  A mouse button consists of a
  2768.                        text prompt inside a box.  By clicking the mouse
  2769.                        after pointing to the button you can select it.
  2770.  
  2771.           Declaration: void DrawMouseButton(int NormalColor,
  2772.                             int SelectedColor,int Number,
  2773.                             int Selection,struct MouseButton *p);
  2774.  
  2775.           Returns:     Nothing.
  2776.  
  2777.           Parameters:
  2778.  
  2779.           The MouseButton information must be given as an array of
  2780.           structures as follows:
  2781.  
  2782.              struct MouseButton{
  2783.                 int Top,Left,Bottom,Right;
  2784.                 int Row,Col;
  2785.                 char String[20];
  2786.                 };
  2787.  
  2788.           where,
  2789.  
  2790.                    Top - upper row coordinate of the Mouse Button area
  2791.                          (integer).
  2792.  
  2793.                   Left - left column coordinate of the Mouse Button area
  2794.                          (integer).
  2795.  
  2796.                 Bottom - lower row coordinate of the Mouse Button area
  2797.                          (integer).
  2798.  
  2799.                  Right - right column coordinate of the Mouse Button area
  2800.                          (integer).
  2801.  
  2802.                    Row - row coordinate of the Mouse Button text (integer).
  2803.  
  2804.                    Col - column coordinate of the Mouse Button text
  2805.                          (integer).
  2806.  
  2807.                 String - the Mouse Button text (maximum of 19 characters.).
  2808.  
  2809.  
  2810.  
  2811.                                       Page -43-
  2812.  
  2813.  
  2814.  
  2815.  
  2816.  
  2817.                           SCL1 Version 2.0 Reference Manual
  2818.  
  2819.  
  2820.                                                             DrawMouseButton
  2821.  
  2822.           The parameters passed to the function are:
  2823.  
  2824.               NormalColor - color attribute used when button is not
  2825.                             selected (integer).
  2826.  
  2827.             SelectedColor - Color used for a selected button (integer).
  2828.  
  2829.                    Number - Number of buttons in the structure (integer).
  2830.  
  2831.                 Selection - Number of the selected button (0 for none)
  2832.                             (integer).
  2833.  
  2834.               MouseButton - pointer to predefined structure.
  2835.  
  2836.           Examples:
  2837.  
  2838.           #include <scl1.h>
  2839.           #include <scl1clor.h>
  2840.  
  2841.           int Color1=WHITE_BLACK;
  2842.           int Color2=BLACK_WHITE;
  2843.  
  2844.           struct MouseButton mb[]={
  2845.              4,35,6,45,   /* Box coordinates */
  2846.              5,38,        /* String position */
  2847.              "Yes",       /* String */
  2848.  
  2849.              10,35,12,45,
  2850.              11,39,
  2851.              "No",
  2852.              };
  2853.  
  2854.           main()
  2855.              {
  2856.              DrawMouseButton(Color1,Color2,2,1,mb);
  2857.              }
  2858.  
  2859.           NOTE: The Dialogue type MouseButton function provides a more
  2860.                 flexible way to perform the same task.
  2861.  
  2862.           See also CheckMouseButton.
  2863.  
  2864.  
  2865.  
  2866.  
  2867.  
  2868.  
  2869.  
  2870.                                       Page -44-
  2871.  
  2872.  
  2873.  
  2874.  
  2875.  
  2876.                           SCL1 Version 2.0 Reference Manual
  2877.  
  2878.  
  2879.                                                                    ErrorBox
  2880.  
  2881.           Function:    ErrorBox
  2882.  
  2883.           Purpose:     Displays a box, centered in the screen, with an
  2884.                        error message.  Several standard error messages have
  2885.                        been defined in the ErrorBox function.  You can add
  2886.                        your own error messages or modify the standard
  2887.                        errors by using the InitUserError function. You can
  2888.                        define the color attributes and a shadow effect for
  2889.                        the error boxes using the ErrorShadowOff,
  2890.                        ErrorShadowOn and SetErrorBoxColor functions.
  2891.  
  2892.           Declaration: void ErrorBox(int ErrNum);
  2893.  
  2894.           Returns:     Nothing.
  2895.  
  2896.           Parameters:
  2897.  
  2898.                 ErrNum - error number corresponding to the error message to
  2899.                          be displayed (integer).
  2900.  
  2901.           The error numbers defined are:
  2902.  
  2903.                        ERROR            DESCRIPTION
  2904.  
  2905.                           2             File not found
  2906.                           3             Path not found
  2907.                           4             Not enough handles
  2908.                           5             Access denied
  2909.                           6             Invalid handle
  2910.                           7             Memory control blocks destroyed
  2911.                           8             Insufficient memory
  2912.                           9             Invalid memory block address
  2913.                          10             Invalid environment
  2914.                          15             Invalid drive
  2915.                          18             No files found
  2916.                          27             Sector not found
  2917.                          29             Write Error
  2918.                          30             Read Error
  2919.                         255             File too Big
  2920.                          -1             DOS Critical Error
  2921.  
  2922.  
  2923.  
  2924.  
  2925.  
  2926.  
  2927.  
  2928.  
  2929.                                       Page -45-
  2930.  
  2931.  
  2932.  
  2933.  
  2934.  
  2935.                           SCL1 Version 2.0 Reference Manual
  2936.  
  2937.  
  2938.                                                                    ErrorBox
  2939.  
  2940.           Example:
  2941.  
  2942.           #include <scl1.h>
  2943.  
  2944.           struct ErrorMess em[]={
  2945.              256,"Please type either Y for YES\nor N for NO",
  2946.              0};
  2947.  
  2948.           main()
  2949.              {
  2950.              int Key;
  2951.  
  2952.              InitUserError(em);
  2953.              printf("\nInstall printer driver? (Y/N)\n");
  2954.  
  2955.              do
  2956.                 {
  2957.                 Key=toupper(getch());
  2958.                 if(Key != 'Y' && Key != 'N')
  2959.                    ErrorBox(256);
  2960.                 else
  2961.                    break;
  2962.                 }while(1);
  2963.              }
  2964.  
  2965.           See ErrorShadowOff, ErrorShadowOn, SetErrorBoxColor and
  2966.           InitUserError.
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.  
  2978.  
  2979.  
  2980.  
  2981.  
  2982.  
  2983.  
  2984.  
  2985.  
  2986.  
  2987.  
  2988.                                       Page -46-
  2989.  
  2990.  
  2991.  
  2992.  
  2993.  
  2994.                           SCL1 Version 2.0 Reference Manual
  2995.  
  2996.  
  2997.                                                              ErrorShadowOff
  2998.                                                               ErrorShadowOn
  2999.  
  3000.           Function:    ErrorShadowOff
  3001.                        ErrorShadowOn
  3002.  
  3003.           Purpose:     Enables or disables a shadow effect when using the
  3004.                        ErrorBox function.  All subsequent calls to the
  3005.                        ErrorBox function will be displayed with (or
  3006.                        without) a shadow effect.
  3007.  
  3008.           Declaration: void ErrorShadowOff(void);
  3009.                        void ErrorShadowOn(void);
  3010.  
  3011.           Returns:     Nothing.
  3012.  
  3013.           Parameters:  None.
  3014.  
  3015.           Example:
  3016.  
  3017.           #include <scl1.h>
  3018.  
  3019.           main
  3020.              {
  3021.              ErrorShadowOn();  /* Turn on shadow effect on error boxes  */
  3022.              .
  3023.              .
  3024.              .
  3025.              ErrorShadowOff(); /* Turn off shadow effect on error boxes */
  3026.              }
  3027.  
  3028.           See ErrorBox, InitUserError and SetErrorBoxColor.
  3029.  
  3030.  
  3031.  
  3032.  
  3033.  
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.  
  3041.  
  3042.  
  3043.  
  3044.  
  3045.  
  3046.  
  3047.                                       Page -47-
  3048.  
  3049.  
  3050.  
  3051.  
  3052.  
  3053.                           SCL1 Version 2.0 Reference Manual
  3054.  
  3055.  
  3056.                                                                  FieldCheck
  3057.  
  3058.           Function:    FieldCheck
  3059.  
  3060.           Purpose:     This function is designed to be used with the
  3061.                        Fields2 function.  When using Fields2 you must
  3062.                        specify a function (in the FData1 structure) to
  3063.                        handle events.  It receives messages from Fields2
  3064.                        and must act upon them returning messages telling
  3065.                        wether the cursor should move to the next/previous
  3066.                        field, stay at the same position or exit the
  3067.                        function.  This function can, at the same time,
  3068.                        monitor the data that is being entered and display
  3069.                        help or error messages, if necessary.  The
  3070.                        FieldCheck function has been designed to handle the
  3071.                        most typical events that are likely to occur when
  3072.                        using Fields2:
  3073.  
  3074.                             TAB - Moves the cursor to the next field.
  3075.  
  3076.                       SHIFT+TAB - Moves the cursor to the previous field.
  3077.  
  3078.                             ESC - Exit Fields2.
  3079.  
  3080.                           ENTER - Its action depends on the active field
  3081.                                   type.  When LineEditor, TagItem or Select
  3082.                                   are active, pressing ENTER moves control
  3083.                                   to the next field.  When ScrollWindow or
  3084.                                   ListWindow are active, pressing ENTER
  3085.                                   will selects the highlighted item.  When
  3086.                                   MouseButton is active, it works as an
  3087.                                   exit key.
  3088.  
  3089.                    MOUSE EVENTS - Handles all mouse events.
  3090.  
  3091.                        It is recommended that you always use FieldCheck. 
  3092.                        Even if you need to define your own field checking
  3093.                        function for data validation or other purposes, you
  3094.                        can still call FieldCheck from your function so that
  3095.                        you don't need to care about the handling the events
  3096.                        just mentioned.
  3097.  
  3098.  
  3099.           Declaration: int FieldCheck(FData2 *p);
  3100.  
  3101.           Returns:     The return value is a message.  Please refer to the
  3102.                        Fields2 function for details.
  3103.  
  3104.  
  3105.  
  3106.                                       Page -48-
  3107.  
  3108.  
  3109.  
  3110.  
  3111.  
  3112.                           SCL1 Version 2.0 Reference Manual
  3113.  
  3114.  
  3115.                                                                  FieldCheck
  3116.  
  3117.           Parameters:
  3118.  
  3119.                 The required parameter is a pointer to the FData2 structure
  3120.                 of the field to be checked.
  3121.  
  3122.           Example:
  3123.  
  3124.              See the example of the Fields2 function.
  3125.  
  3126.  
  3127.  
  3128.  
  3129.  
  3130.  
  3131.  
  3132.  
  3133.  
  3134.  
  3135.  
  3136.  
  3137.  
  3138.  
  3139.  
  3140.  
  3141.  
  3142.  
  3143.  
  3144.  
  3145.  
  3146.  
  3147.  
  3148.  
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.  
  3155.  
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.  
  3165.                                       Page -49-
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.                           SCL1 Version 2.0 Reference Manual
  3172.  
  3173.  
  3174.                                                                      Fields
  3175.  
  3176.           Function:    Fields
  3177.  
  3178.           Purpose:     Get keyboard input using fields.  With this function
  3179.                        you can make data entry screens very easily.  You
  3180.                        can move across the fields using the TAB, SHIFTTAB
  3181.                        keys or the mouse.  The exit key is defined when
  3182.                        calling the function.  You have the capability of
  3183.                        calling a data validation function after finishing
  3184.                        editing each field.  You can also call a help
  3185.                        function associated with each field, this permits
  3186.                        context sensitive help.  When you reach the maximum
  3187.                        field length, as defined by the MaxChar parameter,
  3188.                        the cursor jumps to the next field, thus for special
  3189.                        field types, such as date fields, you can define
  3190.                        three separate data entry fields for the month, day
  3191.                        and year and make them look as one field.
  3192.  
  3193.           Declaration: int Fields(int NColor, int RColor, int NFields,
  3194.                            struct InputFields *ifld, unsigned int ExitKey,
  3195.                            unsigned int HelpKey);
  3196.  
  3197.           Returns:     The returned value is "1" if a key defined as an
  3198.                        exit key is pressed and "-1" if the ESC key is
  3199.                        pressed.
  3200.  
  3201.           Parameters:
  3202.  
  3203.           The field information must be given in a structure as follows:
  3204.  
  3205.           struct InputFields{
  3206.              int PromptLine;
  3207.              int PromptCol;
  3208.              char *Prompt;
  3209.              int FieldLine;
  3210.              int FieldCol;
  3211.              char *FieldBuffer;
  3212.              int MaxChar;
  3213.              int CharType;
  3214.              int (* Helpf)(struct InputFields *p);
  3215.              int (* CheckF)(struct InputFields *p);
  3216.              };
  3217.  
  3218.  
  3219.  
  3220.  
  3221.  
  3222.  
  3223.  
  3224.                                       Page -50-
  3225.  
  3226.  
  3227.  
  3228.  
  3229.  
  3230.                           SCL1 Version 2.0 Reference Manual
  3231.  
  3232.  
  3233.                                                                      Fields
  3234.  
  3235.           Where;
  3236.  
  3237.            InputFields - the structure tag.
  3238.  
  3239.             Promptline - row position where to display the prompt
  3240.                          (integer).
  3241.  
  3242.              PromptCol - column position where to display the prompt
  3243.                          (integer).
  3244.  
  3245.                 Prompt - pointer to the field prompt to be displayed
  3246.                          (char).
  3247.  
  3248.              FieldLine - row position where to display the field (integer).
  3249.  
  3250.               FieldCol - Column position where to display the field
  3251.                          (integer).
  3252.  
  3253.            FieldBuffer - pointer to the buffer to be used to store the
  3254.                          field, it must be one digit larger than the field
  3255.                          size to include the string termination null
  3256.                          character (char).
  3257.  
  3258.                MaxChar - length of the input field (integer).
  3259.  
  3260.               CharType - the mask of valid characters as described in
  3261.                          function CheckChar (integer).
  3262.  
  3263.                  Helpf - pointer to a help function.  This function
  3264.                          receives a pointer to the fields structure and
  3265.                          must be user supplied since it is not defined in
  3266.                          SCL1.H.
  3267.  
  3268.                 CheckF - pointer to a field validation function.  This
  3269.                          function receives a pointer to the fields
  3270.                          structure and must be user supplied since it is
  3271.                          not defined in SCL1.H.  The CheckF must return a
  3272.                          value of "0" if the field fails the test or a
  3273.                          value of "1" to accept the entry.
  3274.  
  3275.  
  3276.  
  3277.  
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.                                       Page -51-
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.                           SCL1 Version 2.0 Reference Manual
  3290.  
  3291.  
  3292.                                                                      Fields
  3293.  
  3294.           The parameters required are:
  3295.  
  3296.                 NColor - color attributes for the prompt display (integer).
  3297.  
  3298.                 RColor - color attributes for the field display (integer).
  3299.  
  3300.                NFields - number of fields (integer).
  3301.  
  3302.            InputFields - pointer to the InputFields structure.
  3303.  
  3304.                ExitKey - key to be used to exit the fields screen (unsigned
  3305.                          integer).
  3306.  
  3307.                HelpKey - key to be used for calling the help function
  3308.                          (unsigned integer).
  3309.  
  3310.  
  3311.           Example:
  3312.  
  3313.           #include <scl1.h>
  3314.           #include <scl1keys.h>
  3315.           #include <scl1clor.h>
  3316.  
  3317.           int test(struct InputFields *p);
  3318.           int helpf(struct InputFields *p);
  3319.  
  3320.           char buffer1[29];
  3321.           char buffer2[29];
  3322.           char buffer3[29];
  3323.           char buffer4[29];
  3324.           char buffer5[13];
  3325.           char buffer6[11];
  3326.           char buffer7[11];
  3327.           char buffer8[11];
  3328.           char buffer9[9];
  3329.           char buffer10[11];
  3330.  
  3331.  
  3332.  
  3333.  
  3334.  
  3335.  
  3336.  
  3337.  
  3338.  
  3339.  
  3340.  
  3341.  
  3342.                                       Page -52-
  3343.  
  3344.  
  3345.  
  3346.  
  3347.  
  3348.                           SCL1 Version 2.0 Reference Manual
  3349.  
  3350.  
  3351.                                                                      Fields
  3352.  
  3353.           struct InputFields data[]={
  3354.              4,3,"Name:",4,11,buffer1,28,CC_LETTER | CC_PUNCTUATION |
  3355.                     CC_CAPITALIZE,helpf,test,
  3356.              6,3,"Address:",6,11,buffer2,28,CC_ANY |
  3357.                     CC_CAPITALIZE,helpf,test,
  3358.              8,3,"City:",8,11,buffer3,28,CC_ANY | CC_CAPITALIZE,helpf,test,
  3359.              10,3,"State:",10,11,buffer4,28,CC_LETTER | CC_PUNCTUATION |
  3360.                    CC_CAPITALIZE,helpf,test,
  3361.              12,3,"Zip:",12,11,buffer5,12,CC_DIGIT,helpf,test,
  3362.              4,44,"Customer Number:",4,60,buffer6,10,CC_DIGIT,helpf,test,
  3363.              6,44,"Amount Due:   $",6,60,buffer7,10,CC_REAL,helpf,test,
  3364.              8,44,"Credit Limit: $",8,60,buffer8,10,CC_REAL,helpf,test,
  3365.              10,44,"Date:",10,49,buffer9,8,CC_ANY,helpf,test,
  3366.              12,44,"Transaction Number:",12,64,buffer10,10,CC_REAL,helpf,
  3367.                    test};
  3368.  
  3369.           main()
  3370.              {
  3371.              Cls(WHITE_BLACK,CLS_ALL);
  3372.              Fields(WHITE_BLACK,BLACK_WHITE,10,data,F10,F1);
  3373.              }
  3374.  
  3375.           helpf(struct InputFields *p)
  3376.           {
  3377.           PushCursor();
  3378.           CursorOff();
  3379.           MessageOn(BLACK_WHITE,"This function would\ndisplay your help
  3380.                     screens.");
  3381.           WaitTime(200);
  3382.           MessageOff();
  3383.           PopCursor();
  3384.           }
  3385.  
  3386.           test(struct InputFields *p)
  3387.           {
  3388.           PushCursor();
  3389.           CursorOff();
  3390.           MessageOn(BLACK_WHITE,"This function could perform\ndata
  3391.                     validation each time\nthe cursor moves to a new
  3392.                     field\nor the user chosses to exit.");
  3393.           WaitTime(300);
  3394.           MessageOff();
  3395.           PopCursor();
  3396.           return(1);
  3397.           }
  3398.           NOTE: The Fields2 function provides a more flexible way to
  3399.                 perform the same task.
  3400.  
  3401.                                       Page -53-
  3402.  
  3403.  
  3404.  
  3405.  
  3406.  
  3407.                           SCL1 Version 2.0 Reference Manual
  3408.  
  3409.  
  3410.                                                                     Fields2
  3411.  
  3412.           Function:    Fields2
  3413.  
  3414.           Purpose:     This function lets you integrate various dialog type
  3415.                        functions to design very powerful data entry and
  3416.                        dialog screens.  This function is similar to Fields
  3417.                        but is more flexible.  Every field can have its
  3418.                        unique help and validation function which you can
  3419.                        create and customize to provide a very useful user
  3420.                        interface.  The screens can contain any of the
  3421.                        following fields:
  3422.  
  3423.                           Line Editor - a field to enter and edit text and
  3424.                                         numeric data.
  3425.  
  3426.                         Scroll Window - a field that displays a window with
  3427.                                         a partial list of items and permits
  3428.                                         tagging or selecting one of them.
  3429.  
  3430.                          Mouse Button - a field that consists of a single
  3431.                                         prompt and permits either to ignore
  3432.                                         it or activate it.
  3433.  
  3434.                              Tag Item - a field that permits to tag one or
  3435.                                         various options.
  3436.  
  3437.                                Select - a field with multiple items that
  3438.                                         permits user selection.
  3439.  
  3440.                           List Window - a field similar to the Scroll
  3441.                                         Window but permits multiple items
  3442.                                         in each line.
  3443.  
  3444.                              Calendar - a field that displays a calendar of
  3445.                                         a given date and permits the user
  3446.                                         to modify the date.
  3447.  
  3448.                          User Defined - a field defined by the user.
  3449.  
  3450.           Declaration: FData2 *Fields2(int Message,FData1 *fd1,
  3451.                                FData2 *fd2);
  3452.  
  3453.           Returns:     This function integrates various dialog type
  3454.                        functions.  See Appendix "E" for a description of
  3455.                        the general operation of these functions. The
  3456.                        returned value is a pointer to the FData2 structure.
  3457.  
  3458.  
  3459.  
  3460.                                       Page -54-
  3461.  
  3462.  
  3463.  
  3464.  
  3465.  
  3466.                           SCL1 Version 2.0 Reference Manual
  3467.  
  3468.  
  3469.                                                                     Fields2
  3470.  
  3471.           Parameters:
  3472.  
  3473.           The field information is given as an array of structures type
  3474.           FData1 as follows, one structure element for each field:
  3475.  
  3476.           Type FData1 structure:
  3477.  
  3478.           typedef struct{
  3479.              int FieldType;
  3480.              void *Structure1;
  3481.              void *Structure2;
  3482.              int (* CheckF)();
  3483.              }FData1;
  3484.  
  3485.           where,
  3486.  
  3487.              FieldType - an integer structure element containing the type
  3488.                          of function for each field defined as follows:
  3489.  
  3490.                          LINE_EDITOR
  3491.                          SCROLL_WINDOW
  3492.                          MOUSE_BUTTON
  3493.                          TAG_ITEM
  3494.                          SELECT
  3495.                          LIST_WINDOW
  3496.                          CALENDAR
  3497.                          USER DEFINED
  3498.  
  3499.             Structure1 - pointer to a structure that contains all the
  3500.                          information required for the field.
  3501.  
  3502.             Structure2 - pointer to a second structure that contains the
  3503.                          field information.  Use "0" if the field type does
  3504.                          not require a second structure.
  3505.  
  3506.                 CheckF - pointer to a function that will be called every
  3507.                          time an event occurs. This function is responsible
  3508.                          for the program flow.  It constantly receives
  3509.                          messages from Fields2 and returns messages to
  3510.                          Fields2 telling it what should be done.  This
  3511.                          allows you to have complete control of the
  3512.                          behavior of Fields2, as well as to perform complex
  3513.                          data validation, context-sensitive help, etc. SCL1
  3514.                          includes a default CheckF called FieldCheck, you
  3515.                          should use this function even if you create your
  3516.                          own CheckF. Please refer to FieldCheck for more
  3517.                          information.
  3518.  
  3519.                                       Page -55-
  3520.  
  3521.  
  3522.  
  3523.  
  3524.  
  3525.                           SCL1 Version 2.0 Reference Manual
  3526.  
  3527.  
  3528.                                                                     Fields2
  3529.  
  3530.              Fields2 needs a secondary structure FData2.  This structure is
  3531.              used for communication between Fields2, the CheckF and the
  3532.              calling program. Each time an event occurs the CheckF is
  3533.              called. By reading the FData2 Message element, the CheckF
  3534.              knows what has just happened. For example, the user could have
  3535.              pressed the TAB key to move to the next field, or he may have
  3536.              clicked the mouse while pointing at another field, or he may
  3537.              have just type a character. CheckF is responsible of telling
  3538.              Fields2 what should be done.
  3539.  
  3540.           Type FData2 structure:
  3541.  
  3542.           typedef struct{
  3543.              int Message;
  3544.              unsigned int EventInfo;
  3545.              FData1 *Structure;
  3546.              int ActiveField;
  3547.              int FieldsNumber;
  3548.              }FData2;
  3549.  
  3550.           where,
  3551.  
  3552.                Message - the message that is transferred between one field
  3553.                          and another (integer).
  3554.  
  3555.              EventInfo - information about the keys that have been pressed
  3556.                          (unsigned integer).
  3557.  
  3558.                 FData1 - pointer to the FData1 structure.
  3559.  
  3560.            ActiveField - structure element that keeps a record of the
  3561.                          current field.  An integer value starting with "0"
  3562.                          for the first field.  This structure element is
  3563.                          used internally by the function (integer).
  3564.  
  3565.           FieldsNumber - structure element that holds the number of fields,
  3566.                          used internally by the function (integer).
  3567.  
  3568.  
  3569.           Type structure FData3:
  3570.  
  3571.           typedef struct{
  3572.              int EventInfo;
  3573.              int (* CheckF)();
  3574.              }FData3;
  3575.  
  3576.  
  3577.  
  3578.                                       Page -56-
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.                           SCL1 Version 2.0 Reference Manual
  3585.  
  3586.  
  3587.                                                                     Fields2
  3588.  
  3589.           where,
  3590.  
  3591.                 EventInfo - information about the last illegal or exit key
  3592.                             that has been pressed (unsigned integer).
  3593.  
  3594.                    CheckF - pointer to check function (integer).
  3595.  
  3596.           NOTE: The information stored in structure type FData3 is used to
  3597.                 define the parameters for user defined fields, in most
  3598.                 applications you can disregard it.
  3599.  
  3600.           Messages:
  3601.  
  3602.           The messages that can be sent to the Fields2 function are:
  3603.  
  3604.                    F_INIT - initialize the Fields2 structures to NULL.
  3605.  
  3606.                    F_DRAW - draw the Fields2 screen.
  3607.  
  3608.                  F_ACTIVE - edit the Fields2 information.
  3609.  
  3610.           When the CheckF is called, after determining what should be done,
  3611.           it can send one the following messages back to Fields2:
  3612.  
  3613.             F_MOUSE_EVENT - internal message used to keep track of where
  3614.                             the mouse has been clicked.
  3615.  
  3616.           F_POSITION_STAY - this message instructs Fields2 not to move to
  3617.                             any other field.  This message is useful when a
  3618.                             validation function has been called and the
  3619.                             field does not pass the validation check, to
  3620.                             permit the user to edit its contents.
  3621.  
  3622.             F_POSITION_UP - move to the next field.
  3623.  
  3624.           F_POSITION_DOWN - move to the previous field.
  3625.  
  3626.            F_SET_POSITION - this message is used to move the cursor to a
  3627.                             desired field. You must first set the
  3628.                             ActiveField structure member to the desired
  3629.                             field number and then return this message.
  3630.  
  3631.                    F_EXIT - instructs Fields2 to exit.
  3632.  
  3633.            F_SET_POS_EXIT - exit after setting a predetermined position.
  3634.  
  3635.  
  3636.  
  3637.                                       Page -57-
  3638.  
  3639.  
  3640.  
  3641.  
  3642.  
  3643.                           SCL1 Version 2.0 Reference Manual
  3644.  
  3645.  
  3646.                                                                     Fields2
  3647.  
  3648.                 F_DRAW_NR - draw the Fields2 display and do not reset the
  3649.                             field values.  When using the F_DRAW message,
  3650.                             Fields2 resets all the fields to their starting
  3651.                             position.
  3652.  
  3653.              F_CHECK_ALL -  when a CheckF senses that the user wants to
  3654.                             exit, it can send this message to Fields2.
  3655.                             Fields2 will call each CheckF defined for each
  3656.                             field. This is very useful if you have a data
  3657.                             validation CheckF for each field. By returning
  3658.                             this message you can be sure that the data in
  3659.                             each field is valid since Fields2 will move to
  3660.                             any field that do not pass the CheckF
  3661.                             validation. If all Fields are valid this
  3662.                             message will behave like an F_EXIT message.
  3663.  
  3664.                 F_COLORS -  all Dialog functions get the color values from
  3665.                             their structures. If you have initialized these
  3666.                             structures as static data and you need to
  3667.                             change the color values you can send this
  3668.                             message to Fields2.  It will change the colors
  3669.                             in each structure to those specified as
  3670.                             additional parameters.  The first value passed
  3671.                             is the Normal Color and the second is the
  3672.                             Reversed Color.
  3673.  
  3674.           Due to the function integrating purpose of Fields2, it does not
  3675.           return messages.
  3676.  
  3677.  
  3678.           Example:
  3679.  
  3680.           #include <scl1.h>
  3681.           #include <scl1keys.h>
  3682.           #include <scl1clor.h>
  3683.  
  3684.           int OurFieldCheck(FData2 *fd2);   /* our CheckF prototype */
  3685.  
  3686.           /* Colors are initialized for a color monitor */
  3687.           int Color1=WHITE_BLUE;
  3688.           int Color2=BLACK_CYAN;
  3689.           int Color3=BROWN_BLACK+HIGHLIGHT;
  3690.  
  3691.  
  3692.  
  3693.  
  3694.  
  3695.  
  3696.                                       Page -58-
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.                           SCL1 Version 2.0 Reference Manual
  3703.  
  3704.  
  3705.                                                                     Fields2
  3706.  
  3707.           /* Our first field will be a Select type */
  3708.  
  3709.           SData1 sd1[]={       /* This is Select's first structure */
  3710.                11,37,"YES",
  3711.                11,47,"NO",
  3712.                0};
  3713.  
  3714.           /* Select's secondary structure: */
  3715.           SData2 sd2={23,11,16,"Create backup files:",0,0,0,0};
  3716.  
  3717.           char buffer[31];   /* Buffer for the data-entry field */
  3718.  
  3719.           /* Our second field will be a LineEditor type */
  3720.           /* This structure defined the LineEditor parameters */
  3721.           LEData led={23,13,16,"Backup Directory:",112,13,34,30,30,
  3722.              CC_PATH+CC_CAPITALIZE, 0,0,buffer,0,0,0,2,1,0,0,0,0,0,0,0};
  3723.  
  3724.           /* The next two fields will of the MouseButton type */
  3725.           /* We must define two structures for the MouseButtons */
  3726.           MBData mb1={23,112,15,28,15,33,15,28,"≡ OK ≡",0,0,0,0};
  3727.  
  3728.           MBData mb2={23,112,15,42,15,51,15,42,"≡ CANCEL ≡",0,0,0,0};
  3729.  
  3730.           /* This is the FData1 structure: */
  3731.           FData1 fd1[]={
  3732.                SELECT,sd1,&sd2,OurFieldCheck,
  3733.                LINE_EDITOR,&led,0,OurFieldCheck,
  3734.                MOUSE_BUTTON,&mb1,0,OurFieldCheck,
  3735.                MOUSE_BUTTON,&mb2,0,OurFieldCheck,
  3736.                0};
  3737.  
  3738.  
  3739.           main()
  3740.           {
  3741.           FData2 fd2; /* Fields2 secondary structure */
  3742.  
  3743.           /* Verify the type of display and change colors if neccessary */
  3744.           if(Video()==MONO)
  3745.               {
  3746.               Color1=WHITE_BLACK;
  3747.               Color2=BLACK_WHITE;
  3748.               Color3=BLACK_WHITE+HIGHLIGHT;
  3749.               }
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.                                       Page -59-
  3756.  
  3757.  
  3758.  
  3759.  
  3760.  
  3761.                           SCL1 Version 2.0 Reference Manual
  3762.  
  3763.  
  3764.                                                                     Fields2
  3765.  
  3766.           /* Clear the screen and draw a box */
  3767.           Cls(Color1,10,13,16,66);
  3768.           Box(Color1,0,10,13,16,66);
  3769.  
  3770.           /* Call Fields2 with a F_INIT message */
  3771.           Fields2(F_INIT,fd1,&fd2);
  3772.  
  3773.           /* Tell Fields2 to modify colors to new values */
  3774.           Fields2(F_COLORS,fd1,&fd2,Color1,Color2);
  3775.  
  3776.           /* Draw fields */
  3777.           Fields2(F_DRAW,fd1,&fd2);
  3778.  
  3779.           /* Activate, now our CheckF will be in control of program flow */
  3780.           Fields2(F_ACTIVE,fd1,&fd2);
  3781.  
  3782.           /* Check the FData2 structure to see if the user presses ESCAPE
  3783.              or selects the CANCEL mouse button for exiting */
  3784.  
  3785.           if(fd2.ActiveField==3 || fd2.EventInfo==ESC)
  3786.               exit(-1);   /* CANCEL selected */
  3787.           else
  3788.               exit(0);    /* OK selected */
  3789.           }
  3790.  
  3791.  
  3792.           /* This is the custom field check function */
  3793.           int OurFieldCheck(FData2 *fd2)
  3794.           {
  3795.           int Mess;
  3796.  
  3797.           /* Let SCL1 FieldCheck function do most of the work */
  3798.           Mess=FieldCheck(fd2);
  3799.  
  3800.           /* Our only job is to watch for the F1 help key. It will be
  3801.              reported by Fields2 with an ILLEGAL_KEY message in the FData2
  3802.              structure element.  The message and the key value will be
  3803.              stored in the EventInfo element */
  3804.  
  3805.           if(fd2->Message == LE_ILLEGAL_KEY && fd2->EventInfo==F1)
  3806.               {
  3807.  
  3808.           /* F1 key pressed, save cursor status and turn it off */
  3809.               PushCursor();
  3810.               CursorOff();
  3811.  
  3812.  
  3813.  
  3814.                                       Page -60-
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.                           SCL1 Version 2.0 Reference Manual
  3821.  
  3822.  
  3823.                                                                     Fields2
  3824.  
  3825.           /* fd2->ActiveField tells us the field number that is active,
  3826.              we will use it to display context sensitive help */
  3827.  
  3828.               switch(fd2->ActiveField)
  3829.                   {
  3830.                   case 0: /* first field */
  3831.                       MessageOn(Color3,"Use arrow keys to select if you\n
  3832.                                         want to create backup files.");
  3833.                       break;
  3834.  
  3835.                   case 1: /* second field */
  3836.                       MessageOn(Color3,"Type Backup files directory.");
  3837.                       break;
  3838.  
  3839.                   case 2: /* third field */
  3840.                       MessageOn(Color3,"Press ENTER to validate\n
  3841.                                         your selection.");
  3842.                       break;
  3843.  
  3844.                   case 3: /* fourth field */
  3845.                       MessageOn(Color3,"Press ENTER or ESC to\n
  3846.                                         cancel your selection.");
  3847.                       break;
  3848.                   }
  3849.               Mess=F_POSITION_STAY;  /* return the position stay message so
  3850.                                         that the cursor does not move */
  3851.               WaitKeyMouse();        /* wait for a key */
  3852.               MessageOff();          /* restore screen */
  3853.               PopCursor();           /* restore cursor */
  3854.               }
  3855.           return(Mess);  /* Mess holds the message Fields2 will receive, a
  3856.                             POSITION_STAY message or the message returned
  3857.                             by FieldCheck */
  3858.           }
  3859.  
  3860.  
  3861.  
  3862.  
  3863.  
  3864.  
  3865.  
  3866.  
  3867.  
  3868.  
  3869.  
  3870.  
  3871.  
  3872.  
  3873.                                       Page -61-
  3874.  
  3875.  
  3876.  
  3877.  
  3878.  
  3879.                           SCL1 Version 2.0 Reference Manual
  3880.  
  3881.  
  3882.                                                                     FileBox
  3883.  
  3884.           Function:    FileBox
  3885.  
  3886.           Purpose:     Displays a box with the directory information for
  3887.                        loading or selecting files.  Fills a buffer with the
  3888.                        selected file/path.  The function accepts mouse
  3889.                        input.
  3890.  
  3891.           Declaration: int FileBox(int NColor, int RColor,char *Buffer);
  3892.  
  3893.           Returns:     The return value is "-1" if the operation is
  3894.                        cancelled by the user by pressing ESC or selecting
  3895.                        the cancel option.
  3896.  
  3897.           Parameters:
  3898.  
  3899.                 NColor - color attributes for normal color display
  3900.                          (integer).
  3901.  
  3902.                 RColor - color attributes for reverse color display
  3903.                          (integer).
  3904.  
  3905.                 Buffer - char pointer to buffer to hold selected filename. 
  3906.                          The search string is placed in the buffer before
  3907.                          calling the function.  If an empty buffer is used
  3908.                          (NO SEARCH STRING SPECIFIED), the function will
  3909.                          place the default path and the "*.*" search string
  3910.                          in the buffer.
  3911.  
  3912.           Example:
  3913.  
  3914.           #include <scl1.h>
  3915.           #include <scl1clor.h>
  3916.  
  3917.           int Color1=BLACK_WHITE;
  3918.           int Color2=WHITE_BLACK;
  3919.  
  3920.           char FileBuf[80]; /* Buffer big enough so that the directory
  3921.                                information will fit */
  3922.           main()
  3923.              {
  3924.              FileBox(Color1,Color2,FileBuf);
  3925.              WriteScreen(Color1,20,12,"You have Selected:");
  3926.              WriteScreen(Color1,20,33,FileBuf);
  3927.              }
  3928.  
  3929.           See also FileBox2 and WFileBox
  3930.  
  3931.  
  3932.                                       Page -62-
  3933.  
  3934.  
  3935.  
  3936.  
  3937.  
  3938.                           SCL1 Version 2.0 Reference Manual
  3939.  
  3940.  
  3941.                                                                    FileBox2
  3942.  
  3943.           Function:    FileBox2
  3944.  
  3945.           Purpose:     Displays a box with the directory information for
  3946.                        loading or selecting files.  Fills a buffer with the
  3947.                        selected file/path.  The function accepts mouse
  3948.                        input. The function automatically senses the current
  3949.                        video mode and adjusts the display accordingly.
  3950.  
  3951.           Declaration: int FileBox2(int Message, FBData *p)
  3952.  
  3953.           Returns:     This is a dialog derived function. See Appendix "E"
  3954.                        for a description of the general operation of these
  3955.                        functions.  The return values are the messages
  3956.                        described in the Messages section.
  3957.  
  3958.           Parameters:
  3959.  
  3960.           The file box information is given in a structure type FBData as
  3961.           follows:
  3962.  
  3963.           Structure type FBData;
  3964.  
  3965.           typedef struct{
  3966.              int NColor;
  3967.              int RColor;
  3968.              int UpperRow;
  3969.              int LeftCol;
  3970.              int LowerRow;
  3971.              int RightCol;
  3972.              char *Filename;
  3973.              int Attrib;
  3974.              }FBData;
  3975.  
  3976.           where,
  3977.  
  3978.                 NColor - normal color for the file box display (integer).
  3979.  
  3980.                 RColor - reversed color for the file box display (integer).
  3981.  
  3982.               UpperRow - upper row coordinate for the file box's display
  3983.                          (integer).
  3984.  
  3985.                LeftCol - left column coordinate for the file box's display
  3986.                          (integer).
  3987.  
  3988.               LowerRow - lower row coordinate for the file box's display
  3989.                          (integer).
  3990.  
  3991.                                       Page -63-
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.                           SCL1 Version 2.0 Reference Manual
  3998.  
  3999.  
  4000.                                                                    FileBox2
  4001.  
  4002.               RightCol - right column coordinate for the file box's display
  4003.                          (integer).
  4004.  
  4005.               Filename - pointer to buffer to hold the selected filename.
  4006.                          The search string is placed in the buffer before
  4007.                          calling the function.  If an empty buffer is used
  4008.                          (NO SEARCH STRING SPECIFIED), the function will
  4009.                          place the default path and the "*.*" search string
  4010.                          into the buffer.
  4011.  
  4012.                 Attrib - file attributes as defined by the DOS. Please
  4013.                          refer to Appendix "A", FILE FUNCTIONS, for more
  4014.                          details (integer).
  4015.  
  4016.           Messages:
  4017.  
  4018.           The following messages can be sent to FileBox2:
  4019.  
  4020.                   FB_INIT - initialize the FBData structure to NULL and set
  4021.                             the following default values:
  4022.  
  4023.                             NColor - set to white characters in a black
  4024.                                      background or the normal color defined
  4025.                                      by calling SetDialogColors.
  4026.  
  4027.                             RColor - set to black characters in a white
  4028.                                      background or the reversed color
  4029.                                      defined by calling SetDialogColors.
  4030.  
  4031.                           UpperRow - set to row "5".
  4032.  
  4033.                            LeftCol - set to column "20" for 80 column
  4034.                                      displays or to column "0" for 40
  4035.                                      column displays.
  4036.  
  4037.                           LowerRow - set to row "19" for 25 row displays or
  4038.                                      to row "36" for 43 row displays.
  4039.  
  4040.                           RightCol - set to column "39" for 40 column
  4041.                                      displays and "59" for 80 column
  4042.                                      displays.
  4043.  
  4044.                             Attrib - files and sub-directories.
  4045.  
  4046.                   FB_DRAW - draw the FileBox to the screen.
  4047.  
  4048.  
  4049.  
  4050.                                       Page -64-
  4051.  
  4052.  
  4053.  
  4054.  
  4055.  
  4056.                           SCL1 Version 2.0 Reference Manual
  4057.  
  4058.  
  4059.                                                                    FileBox2
  4060.  
  4061.                 FB_ACTIVE - browse through the displayed filenames and
  4062.                             permit a selection or to cancel the operation
  4063.                             using the cursor movement keys as follows:
  4064.  
  4065.                          Key                      action
  4066.  
  4067.                        Up Arrow         cursor one item up.
  4068.                        Down Arrow       cursor one item down.
  4069.                        END              cursor to end of file list.
  4070.                        HOME             cursor to beginning of list.
  4071.                        Page Up          cursor one screen up.
  4072.                        Page Down        cursor one screen down.
  4073.  
  4074.                 FB_RESET -  when this message is sent the filebox variables
  4075.                             are reset to the default value.  If the exit
  4076.                             keys have not been defined they are set to the
  4077.                             default exit keys.
  4078.  
  4079.           The following messages can be returned by FileBox2:
  4080.  
  4081.                     FB_OK - the action requested has been performed and a
  4082.                             file has been selected.
  4083.  
  4084.                 FB_CANCEL - the operation has been cancelled.
  4085.  
  4086.           Example:
  4087.  
  4088.           #include <scl1.h>
  4089.           #include <scl1clor.H>
  4090.  
  4091.           char Buffer[80];
  4092.           int Color1=WHITE_BLACK,Color2=BLACK_WHITE;
  4093.  
  4094.           main()
  4095.              {
  4096.              FBData fbd;
  4097.  
  4098.              FileBox2(FB_INIT,&fbd);   /* initialize the FBData structure*/
  4099.              fbd.NColor=Color1;        /* change display colors */
  4100.              fbd.RColor=Color2;
  4101.              fbd.Filename=Buffer;      /* buffer to hold directory info */
  4102.              fbd.Attrib=F_READ_ONLY+F_HIDDEN+F_SYSTEM+F_DIRECTORY;
  4103.                                        /* set files attributes */
  4104.              FileBox2(FB_DRAW,&fbd);   /* display FileBox */
  4105.              FileBox2(FB_ACTIVE,&fbd); /* let user make a selection */
  4106.              }
  4107.           See also FileBox and WfileBox.
  4108.  
  4109.                                       Page -65-
  4110.  
  4111.  
  4112.  
  4113.  
  4114.  
  4115.                           SCL1 Version 2.0 Reference Manual
  4116.  
  4117.  
  4118.                                                                    File2Buf
  4119.  
  4120.           Function:    File2Buf
  4121.  
  4122.           Purpose:     Reads a file into a buffer.
  4123.  
  4124.           Declaration: int File2Buf(char* Filename, char* Buffer,
  4125.                            unsigned int* MaxSize);
  4126.  
  4127.           Returns:     The return value is "0" if no errors occurs.  When
  4128.                        errors occur the returned values are as follows: a
  4129.                        value of "-1" indicates that a critical DOS error
  4130.                        has occurred, a value of "255" indicates that the
  4131.                        file is larger than the size specified with MaxSize,
  4132.                        and the standard DOS error code for other errors. 
  4133.                        You must have called TrapInt24 before in order to
  4134.                        trap critical errors.  The number of bytes read are
  4135.                        stored in MaxSize.
  4136.  
  4137.           Parameters:
  4138.  
  4139.              Filename - valid pathname of the file to be read (char).
  4140.  
  4141.                 Buffer - buffer to hold the information (char).
  4142.  
  4143.                MaxSize - number of bytes to read (unsigned integer).
  4144.  
  4145.  
  4146.           Example:
  4147.  
  4148.           #include <scl1.h>
  4149.  
  4150.           char buffer[]="We'll write this data to disk and read it
  4151.                          back.\n";
  4152.  
  4153.           main()
  4154.              {
  4155.              int Error;
  4156.              unsigned int size;
  4157.  
  4158.              if(Error=Buf2Disk("FILE.1",buffer,sizeof(buffer)))
  4159.                 {
  4160.                 printf("Error writing file # %i\n",Error);
  4161.                 exit(-1);
  4162.                 }
  4163.  
  4164.  
  4165.  
  4166.  
  4167.  
  4168.                                       Page -66-
  4169.  
  4170.  
  4171.  
  4172.  
  4173.  
  4174.                           SCL1 Version 2.0 Reference Manual
  4175.  
  4176.  
  4177.                                                                    File2Buf
  4178.  
  4179.              size=sizeof(buffer);
  4180.              memset(buffer,0,size);
  4181.              if(Error=File2Buf("FILE.1",buffer,&size))
  4182.                 printf("Error reading file # %i\n",Error);
  4183.              else
  4184.                 printf("%s\n",buffer);
  4185.              }
  4186.           See also File2Buff and TrapInt24.
  4187.  
  4188.  
  4189.  
  4190.  
  4191.  
  4192.  
  4193.  
  4194.  
  4195.  
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.  
  4220.  
  4221.  
  4222.  
  4223.  
  4224.  
  4225.  
  4226.  
  4227.                                       Page -67-
  4228.  
  4229.  
  4230.  
  4231.  
  4232.  
  4233.                           SCL1 Version 2.0 Reference Manual
  4234.  
  4235.  
  4236.                                                                   FillBlock
  4237.  
  4238.           Function:    FillBlock
  4239.  
  4240.           Purpose:     Fills a screen area, defined with the parameters
  4241.                        passed to the function, with a given character.
  4242.  
  4243.           Declaration: void FillBlock(int Color, int UpperRow,
  4244.                             int LeftCol, int LowerRow, int RightCol,
  4245.                             int Character);
  4246.  
  4247.           Returns:     Nothing
  4248.  
  4249.           Parameters:
  4250.  
  4251.                  Color - color attribute for the display (integer).
  4252.  
  4253.               UpperRow - upper row coordinate of the display (integer).
  4254.  
  4255.                LeftCol - left column coordinate of the display (integer).
  4256.  
  4257.               LowerRow - lower row coordinate of the display (integer).
  4258.  
  4259.               RightCol - right column coordinate of the display (integer).
  4260.  
  4261.              Character - character to be used for filling the screen area. 
  4262.                          This can be any valid character (integer).
  4263.  
  4264.              (Note: the home position is row 0, column 0.)
  4265.  
  4266.           Example:
  4267.  
  4268.           #include <scl1.h>
  4269.           #include <scl1clor.h>
  4270.  
  4271.           int Color1=BLACK_WHITE;
  4272.  
  4273.           main()
  4274.              {
  4275.              FillBlock(Color1,2,2,20,40,178);
  4276.              /* Will fill the area between rows 2-10 and columns 20-40 with
  4277.                 character 178. */
  4278.              }
  4279.  
  4280.  
  4281.  
  4282.  
  4283.  
  4284.  
  4285.  
  4286.                                       Page -68-
  4287.  
  4288.  
  4289.  
  4290.  
  4291.  
  4292.                           SCL1 Version 2.0 Reference Manual
  4293.  
  4294.  
  4295.                                                                   FindFirst
  4296.                                                                    FindNext
  4297.  
  4298.           Function:    FindFirst
  4299.                        FindNext
  4300.  
  4301.           Purpose:     Searches a disk directory for the file that matches
  4302.                        the specified search attributes using DOS system
  4303.                        call 0x4e.  After finding the first matching file
  4304.                        you must use FindNext to get subsequent matching
  4305.                        files.
  4306.  
  4307.           Declaration: int FindFirst(char *SearchString,struct FileData
  4308.                                *Buffer,int SearchAtr);
  4309.  
  4310.                        int FindNext(void);
  4311.  
  4312.           Returns:     The return value is "0" if no error occurs or the
  4313.                        DOS error code if an error occurs.  (See Appendix
  4314.                        "A", FILE FUNCTIONS, for more information). DOS
  4315.                        error code "18" is returned when no more files are
  4316.                        found.
  4317.  
  4318.           Parameters:
  4319.  
  4320.              SearchString - pointer to a string with the search mask to be
  4321.                             used (for example C:\BIN\*.EXE). If a matching
  4322.                             file is found the FileData structure is filled
  4323.                             with the file information.
  4324.  
  4325.                  FileData - pointer to a structure of type FileData defined
  4326.                             in SCL1.H:
  4327.  
  4328.                 struct FileData{
  4329.                    char reserved[21];
  4330.                    char attrib;
  4331.                    struct FILETIME time;
  4332.                    struct FILEDATE date;
  4333.                    long size;
  4334.                    char name[13];
  4335.                    };
  4336.  
  4337.              where,
  4338.  
  4339.                  reserved - is an area reserved by DOS for subsequent calls
  4340.                             to FindNext (char).
  4341.  
  4342.  
  4343.  
  4344.  
  4345.                                       Page -69-
  4346.  
  4347.  
  4348.  
  4349.  
  4350.  
  4351.                           SCL1 Version 2.0 Reference Manual
  4352.  
  4353.  
  4354.                                                                   FindFirst
  4355.                                                                    FindNext
  4356.  
  4357.                    attrib - Identifies the type of file found. Can be one
  4358.                             or more of the following constants defined in
  4359.                             SCL1.H: (use an OR operation to add them)
  4360.  
  4361.                                      F_READ_ONLY
  4362.                                      F_HIDDEN
  4363.                                      F_SYSTEM
  4364.                                      F_VOLUME
  4365.                                      F_DIRECTORY
  4366.                                      F_ARCHIVE
  4367.  
  4368.                      time - structure with bit-fields members that holds
  4369.                             the time when the file was created or last
  4370.                             updated. FILETIME structure is defined in
  4371.                             SCL1.H:
  4372.  
  4373.                             struct FILETIME{
  4374.                                   unsigned int seconds:5;
  4375.                                   unsigned int minutes:6;
  4376.                                   unsigned int hours:5;
  4377.                                   };
  4378.  
  4379.                             where,
  4380.  
  4381.                               seconds - integer value from "0" to "59".
  4382.                               minutes - integer value from "0" to "59".
  4383.                                 hours - integer value from "0" to "24".
  4384.  
  4385.                      date - structure with bit-fields members that holds
  4386.                             the date when the file was created or last
  4387.                             updated. FILEDATE structure is defined in
  4388.                             SCL1.H:
  4389.  
  4390.                             struct FILEDATE{
  4391.                                   unsigned int day:5;
  4392.                                   unsigned int month:4;
  4393.                                   unsigned int year:7;
  4394.                                   };
  4395.  
  4396.                             where,
  4397.  
  4398.                                  year - integer value from "0" to "119", to
  4399.                                         get the real year add "80" to this
  4400.                                         value.
  4401.  
  4402.                                 month - integer value from "1" to "12".
  4403.  
  4404.                                       Page -70-
  4405.  
  4406.  
  4407.  
  4408.  
  4409.  
  4410.                           SCL1 Version 2.0 Reference Manual
  4411.  
  4412.  
  4413.                                                                   FindFirst
  4414.                                                                    FindNext
  4415.  
  4416.                                   day - integer value from "1" to "31".
  4417.  
  4418.                      size - File's size in bytes (long integer).
  4419.  
  4420.                      name - File's name.
  4421.  
  4422.                 SearchAtr - is the DOS file attribute of eligible files.
  4423.                             The following attribute constants have been
  4424.                             defined in SCL1.H:
  4425.  
  4426.                    F_ARCHIVE - only archive files will be reported.
  4427.  
  4428.                  F_DIRECTORY - archive and directories will be reported.
  4429.  
  4430.                  F_READ_ONLY - archive and read-only files will be
  4431.                                reported.
  4432.  
  4433.                     F_HIDDEN - archive and hidden files will be reported.
  4434.  
  4435.                     F_SYSTEM - archive and system files will be reported.
  4436.  
  4437.                     F_VOLUME - ONLY the volume label is reported.
  4438.  
  4439.              NOTE: This functions sets the DTA (Disk Transfer Area) to
  4440.                    point to the FileData structure. Is important that you
  4441.                    do not modify the DTA between a call to FindFirst and
  4442.                    FindNext.
  4443.  
  4444.           Example:
  4445.  
  4446.           #include <scl1.h>
  4447.  
  4448.           #define NO_MORE_FILES   18
  4449.  
  4450.           static void printinfo(struct FileData *fd);
  4451.  
  4452.           main()
  4453.           {
  4454.           struct FileData fd;  /* file info will be stored here */
  4455.           int RetVal;
  4456.  
  4457.           RetVal=FindFirst("*.*",&fd,F_VOLUME);   /* read volume label */
  4458.           if(RetVal==NO_MORE_FILES)          /* no more files? */
  4459.               printf("\nVolume has no label\n\n");
  4460.           else
  4461.               printf("\nVolume label: %s\n\n",fd.name);
  4462.  
  4463.                                       Page -71-
  4464.  
  4465.  
  4466.  
  4467.  
  4468.  
  4469.                           SCL1 Version 2.0 Reference Manual
  4470.  
  4471.  
  4472.                                                                   FindFirst
  4473.                                                                    FindNext
  4474.  
  4475.              /* read other files. Subdirectories, hidden, system and
  4476.                 archive files */
  4477.  
  4478.           RetVal=FindFirst("*.*",&fd,F_DIRECTORY | F_SYSTEM | F_HIDDEN);
  4479.  
  4480.              /* Get filenames while no error is reported */
  4481.  
  4482.           while(RetVal==0)
  4483.               {
  4484.               printinfo(&fd);     /* print file information */
  4485.               RetVal=FindNext();  /* get next file */
  4486.               }
  4487.           }
  4488.  
  4489.           static void printinfo(struct FileData *fd)
  4490.           {
  4491.           printf("%-13s",fd->name); /* print file name */
  4492.  
  4493.              /* if file is not a directory, print file size */
  4494.  
  4495.           if(fd->attrib == F_DIRECTORY)
  4496.               printf("  <DIR>");
  4497.           else
  4498.               printf("%7li",fd->size);
  4499.  
  4500.           /* print date and time */
  4501.  
  4502.           printf("  %.2i-%.2i-%.2i  %.2i:%.2i:%.2i\n",fd->date.month,
  4503.                  fd->date.day,fd->date.year+80,fd->time.hours,
  4504.                  fd->time.minutes, fd->time.seconds);
  4505.           }
  4506.  
  4507.  
  4508.  
  4509.  
  4510.  
  4511.  
  4512.  
  4513.  
  4514.  
  4515.  
  4516.  
  4517.  
  4518.  
  4519.  
  4520.  
  4521.  
  4522.                                       Page -72-
  4523.  
  4524.  
  4525.  
  4526.  
  4527.  
  4528.                           SCL1 Version 2.0 Reference Manual
  4529.  
  4530.  
  4531.                                                                   GetCurCol
  4532.                                                                  GetCurLine
  4533.  
  4534.           Function:    GetCurCol
  4535.                        GetCurLine
  4536.  
  4537.           Purpose:     Returns the current cursor position.
  4538.  
  4539.           Declaration: char GetCurCol(char);
  4540.                        char GetCurLine(void);
  4541.  
  4542.           Returns:     GetCurCol returns the column position and GetCurLine
  4543.                        returns the row position.
  4544.  
  4545.           Parameters:  None
  4546.  
  4547.           Example:
  4548.  
  4549.           #include <scl1.h>
  4550.  
  4551.           main()
  4552.              {
  4553.              int Line,Col;
  4554.  
  4555.              Col=GetCurCol();
  4556.              Line=GetCurLine();
  4557.              printf("Cursor position before writing this string:
  4558.                     %i, %i\n",Line,Col);
  4559.              }
  4560.  
  4561.  
  4562.  
  4563.  
  4564.  
  4565.  
  4566.  
  4567.  
  4568.  
  4569.  
  4570.  
  4571.  
  4572.  
  4573.  
  4574.  
  4575.  
  4576.  
  4577.  
  4578.  
  4579.  
  4580.  
  4581.                                       Page -73-
  4582.  
  4583.  
  4584.  
  4585.  
  4586.  
  4587.                           SCL1 Version 2.0 Reference Manual
  4588.  
  4589.  
  4590.                                                               GetCurrentDir
  4591.  
  4592.           Function:    GetCurrentDir
  4593.  
  4594.           Purpose:     Returns an ASCII string holding the default drive
  4595.                        and path.
  4596.  
  4597.           Declaration: int GetCurrentDir(char *PathBuffer);
  4598.  
  4599.           Returns:     The return value is "0" if no error occurs or the
  4600.                        DOS error code if an error occurs.  (See Appendix
  4601.                        "A", FILE FUNCTIONS, for more information).
  4602.  
  4603.           Parameters:
  4604.  
  4605.             PathBuffer - pointer to a buffer to hold the pathname and drive
  4606.                          letter (char).
  4607.  
  4608.           Example:
  4609.  
  4610.           #include <slc1.h>
  4611.  
  4612.           main()
  4613.              {
  4614.              int RetCode;
  4615.              char Buffer[80];
  4616.  
  4617.              RetCode=GetCurrentDir(Buffer);
  4618.              }
  4619.  
  4620.  
  4621.  
  4622.  
  4623.  
  4624.  
  4625.  
  4626.  
  4627.  
  4628.  
  4629.  
  4630.  
  4631.  
  4632.  
  4633.  
  4634.  
  4635.  
  4636.  
  4637.  
  4638.  
  4639.  
  4640.                                       Page -74-
  4641.  
  4642.  
  4643.  
  4644.  
  4645.  
  4646.                           SCL1 Version 2.0 Reference Manual
  4647.  
  4648.  
  4649.                                                                  GetCurSize
  4650.  
  4651.           Function:    GetCurSize
  4652.  
  4653.           Purpose:     Saves the current cursor size in variable
  4654.                        GCS_CursorSize and returns the current cursor size.
  4655.  
  4656.           Declaration: int GetCurSize(void);
  4657.  
  4658.           Returns:     The return value is the current cursor size.
  4659.  
  4660.           Parameters:  None
  4661.  
  4662.           Example:
  4663.  
  4664.           #include <scl1.h>
  4665.  
  4666.           main()
  4667.              {
  4668.              GetCurSize();                   /* Save actual size */
  4669.              BigCursor();                    /* Change size */
  4670.              SetCurSize(GCS_CursorSize);     /* Restore previous size */
  4671.              }
  4672.  
  4673.  
  4674.  
  4675.  
  4676.  
  4677.  
  4678.  
  4679.  
  4680.  
  4681.  
  4682.  
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.  
  4691.  
  4692.  
  4693.  
  4694.  
  4695.  
  4696.  
  4697.  
  4698.  
  4699.                                       Page -75-
  4700.  
  4701.  
  4702.  
  4703.  
  4704.  
  4705.                           SCL1 Version 2.0 Reference Manual
  4706.  
  4707.  
  4708.                                                                     GetDate
  4709.  
  4710.           Function:    GetDate
  4711.  
  4712.           Purpose:     Gets the system date.
  4713.  
  4714.           Declaration: struct DateData * GetDate(void);
  4715.  
  4716.           Returns:     The return value is a pointer to the DateData
  4717.                        structure defined as follows:
  4718.  
  4719.           struct DateData{
  4720.              int WeekDay;
  4721.              int MonthDay;
  4722.              int Month;
  4723.              int Year;
  4724.              };
  4725.  
  4726.           where,
  4727.  
  4728.                WeekDay - day of the week in numerical format
  4729.                          (0=sunday,etc.) (integer).
  4730.  
  4731.               MonthDay - day of the month (1 - 31) (integer).
  4732.  
  4733.                  Month - month number (1 - 12) (integer).
  4734.  
  4735.                   Year - year (1980 - 2099) (integer).
  4736.  
  4737.           Parameters:  None
  4738.  
  4739.           Example:
  4740.  
  4741.  
  4742.           #include <scl1.h>
  4743.           #include <scl1clor.h>
  4744.  
  4745.           char *Day[]={"Sunday","Monday","Tuesday","Wednesday",
  4746.                       "Thursday","Friday","Saturday"};
  4747.  
  4748.           char *Month[]={"","January","February","March","April","May",
  4749.                         "June","July","August","September","October",
  4750.                         "November","December"};
  4751.  
  4752.  
  4753.  
  4754.  
  4755.  
  4756.  
  4757.  
  4758.                                       Page -76-
  4759.  
  4760.  
  4761.  
  4762.  
  4763.  
  4764.                           SCL1 Version 2.0 Reference Manual
  4765.  
  4766.  
  4767.                                                                     GetDate
  4768.  
  4769.           main()
  4770.              {
  4771.              struct DateData *p;
  4772.  
  4773.              p=GetDate();
  4774.              /* p points to DateData structure:
  4775.                 p->WeekDay = day of the week (0=Sunday),
  4776.                 p->MonthDay = day (1-31),
  4777.                 p->Month = month (1-12)
  4778.                 p->Year = year (1980 - 2099).
  4779.  
  4780.              The month and day numbers reported by GetDate will be used as
  4781.              index to the week and months names arrays we have previously
  4782.              defined. Use printf to print this data */
  4783.  
  4784.              printf("Today is %s, %s %d,%d",Day[p->WeekDay],
  4785.                      Month[p->Month],p->MonthDay,p->Year);
  4786.  
  4787.              }
  4788.  
  4789.  
  4790.  
  4791.  
  4792.  
  4793.  
  4794.  
  4795.  
  4796.  
  4797.  
  4798.  
  4799.  
  4800.  
  4801.  
  4802.  
  4803.  
  4804.  
  4805.  
  4806.  
  4807.  
  4808.  
  4809.  
  4810.  
  4811.  
  4812.  
  4813.  
  4814.  
  4815.  
  4816.  
  4817.                                       Page -77-
  4818.  
  4819.  
  4820.  
  4821.  
  4822.  
  4823.                           SCL1 Version 2.0 Reference Manual
  4824.  
  4825.  
  4826.                                                             GetDefaultDrive
  4827.  
  4828.           Function:    GetDefaultDrive
  4829.  
  4830.           Purpose:     Gets the default disk drive.
  4831.  
  4832.           Declaration: int GetDefaultDrive(void);
  4833.  
  4834.           Returns:     The return value indicates the default drive number,
  4835.                        0=A, 1=B, etc.
  4836.  
  4837.           Parameters:  None
  4838.  
  4839.           Example:
  4840.  
  4841.           #include <slc1.h>
  4842.  
  4843.           main()
  4844.              {
  4845.              int Drive;
  4846.  
  4847.              Drive=GetDefaultDrive();
  4848.              printf("The default drive is %c\n",'A'+Drive)
  4849.              }
  4850.  
  4851.  
  4852.  
  4853.  
  4854.  
  4855.  
  4856.  
  4857.  
  4858.  
  4859.  
  4860.  
  4861.  
  4862.  
  4863.  
  4864.  
  4865.  
  4866.  
  4867.  
  4868.  
  4869.  
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.                                       Page -78-
  4877.  
  4878.  
  4879.  
  4880.  
  4881.  
  4882.                           SCL1 Version 2.0 Reference Manual
  4883.  
  4884.  
  4885.                                                            GetDiskFreeSpace
  4886.  
  4887.           Function:    GetDiskFreeSpace
  4888.  
  4889.           Purpose:     Gets the selected disk drive's free space in bytes.
  4890.  
  4891.           Declaration: long GetDefaultDrive(int Drive);
  4892.  
  4893.           Returns:     The number of bytes free in the selected drive, "-1"
  4894.                        if TrapInt24 was initialized and a critical error
  4895.                        occurs or "-2" if the drive number is illegal.
  4896.  
  4897.           Parameters:
  4898.  
  4899.                  Drive - Drive number (integer):
  4900.                      0 = default
  4901.                      1 = A
  4902.                      2 = B, etc.
  4903.  
  4904.           Example:
  4905.  
  4906.           #include <slc1.h>
  4907.  
  4908.           main()
  4909.              {
  4910.  
  4911.              printf("Disk Free Space=%li\n",GetDiskFreeSpace(0));
  4912.              }
  4913.  
  4914.  
  4915.  
  4916.  
  4917.  
  4918.  
  4919.  
  4920.  
  4921.  
  4922.  
  4923.  
  4924.  
  4925.  
  4926.  
  4927.  
  4928.  
  4929.  
  4930.  
  4931.  
  4932.  
  4933.  
  4934.  
  4935.                                       Page -79-
  4936.  
  4937.  
  4938.  
  4939.  
  4940.  
  4941.                           SCL1 Version 2.0 Reference Manual
  4942.  
  4943.  
  4944.                                                            GetExtendedAscii
  4945.  
  4946.           Function:    GetExtendedAscii
  4947.  
  4948.           Purpose:     Changes ALT+Key combination into Extended Ascii
  4949.                        character according to 4 tables:
  4950.  
  4951.                        Table 0 - Spanish characters.
  4952.                        Table 1 - Other language characters.
  4953.                        Table 2 - Graphic characters.
  4954.                        Table 3 - Greek letters, math symbols.
  4955.  
  4956.           Declaration: unsigned int GetExtendedAscii(unsigned int Key);
  4957.  
  4958.           Returns:     The Ascii Code, if found (<"255"), or original
  4959.                        Scan+Ascii Code, if not found (>"255").
  4960.  
  4961.           Table 0 is the default. To change table set variable GE_CharTable
  4962.           to desired table number.  The tables have been defined as
  4963.           follows:
  4964.  
  4965.                 Table 0 -
  4966.                 ALT+   aeiouvnm12
  4967.                        áéíóúüñÑ¡¿
  4968.  
  4969.  
  4970.                 Table 1 -
  4971.                 ALT+   123456789  qwertyuiop  asdfghjkl  zxcvbnm
  4972.                        âêîôû£₧ƒ¥  áéíóúÿçÇñÑ  àèìòùÄÉÖÜ  äëïöü¡¿
  4973.  
  4974.  
  4975.                 Table 2 -
  4976.                 ALT+   123456789  qwertyuiop  asdfghjkl  zxcvbnm
  4977.                        ╔╗╚╝═║░▒▓  ╦╠╣╩╬█▄▌▐▀  ┌┐└┘─│°∙·  ┬├┤┴┼«»
  4978.  
  4979.  
  4980.                 Table 3 -
  4981.                 ALT+   123456789  qwertyui  asdfghjkl  zx
  4982.                        αßΓπΣσµτΦ  ΘΩδ∞φε∩≡  ±≥≤⌠⌡÷≈√ⁿ  ² 
  4983.  
  4984.  
  4985.           (Note: You will not be to print the correct characters if your
  4986.           printer does not support the IBM extended ASCII character set.)
  4987.  
  4988.           Parameters:
  4989.  
  4990.                    Key - Scan and ASCII code of a key (unsigned integer).
  4991.  
  4992.  
  4993.  
  4994.                                       Page -80-
  4995.  
  4996.  
  4997.  
  4998.  
  4999.  
  5000.                           SCL1 Version 2.0 Reference Manual
  5001.  
  5002.  
  5003.                                                            GetExtendedAscii
  5004.  
  5005.           Example:
  5006.  
  5007.           #include <slc1.h>
  5008.           #include <scl1keys.h>
  5009.  
  5010.           main()
  5011.              {
  5012.              unsigned int key;
  5013.  
  5014.              do
  5015.                 {
  5016.                 printf("Press an ALT + Key combination...");
  5017.                 key=GetKey();
  5018.                 if((key=GetExtendenAscii(key)) < 255)
  5019.                    {
  5020.                    printf("%c\n",key);
  5021.                    break;
  5022.                    }
  5023.                 else
  5024.                    printf("\nThis key combination has not been defined, 
  5025.                             try again!\n:);
  5026.                 }while(1);
  5027.              }
  5028.  
  5029.  
  5030.  
  5031.  
  5032.  
  5033.  
  5034.  
  5035.  
  5036.  
  5037.  
  5038.  
  5039.  
  5040.  
  5041.  
  5042.  
  5043.  
  5044.  
  5045.  
  5046.  
  5047.  
  5048.  
  5049.  
  5050.  
  5051.  
  5052.  
  5053.                                       Page -81-
  5054.  
  5055.  
  5056.  
  5057.  
  5058.  
  5059.                           SCL1 Version 2.0 Reference Manual
  5060.  
  5061.  
  5062.                                                                    GetFiles
  5063.  
  5064.           Function:    GetFiles
  5065.  
  5066.           Purpose:     Searches for the files that match the specified
  5067.                        search string and attributes.  Sets global variable
  5068.                        GF_FileNumber to the number of files found and
  5069.                        initialize an array of pointers, GF_PointerBuf,
  5070.                        which will point to the filenames.
  5071.  
  5072.           Declaration: int GetFiles(char *SearchString,int SearchAtr);
  5073.  
  5074.           Returns:     The return value is "0" if no error occurs or the
  5075.                        DOS error code if an error occurs.  (See Appendix
  5076.                        "A", FILE FUNCTIONS, for more information).
  5077.  
  5078.           Parameters:
  5079.  
  5080.           SearchString - char pointer to the desired search string.
  5081.  
  5082.              SearchAtr - variable that defines the desired search
  5083.                          attributes (integer).
  5084.  
  5085.           Example:
  5086.  
  5087.           #include <scl1.h>
  5088.  
  5089.           main()
  5090.              {
  5091.              int i;
  5092.  
  5093.  
  5094.              if(i=GetFiles("*.*",F_ARCHIVE+F_DIRECTORY))
  5095.                 printf("GetFiles reports error number %i\n",i);
  5096.              else
  5097.                 {
  5098.                 for(i=0;i < GF_FileNumber;++i)
  5099.                    printf("%s\n",GF_PointerBuf[i]);
  5100.                 }
  5101.              }
  5102.  
  5103.  
  5104.  
  5105.  
  5106.  
  5107.  
  5108.  
  5109.  
  5110.  
  5111.  
  5112.                                       Page -82-
  5113.  
  5114.  
  5115.  
  5116.  
  5117.  
  5118.                           SCL1 Version 2.0 Reference Manual
  5119.  
  5120.  
  5121.                                                                 GetFileMode
  5122.  
  5123.           Function:    GetFileMode
  5124.  
  5125.           Purpose:     Gets the selected file's attributes.
  5126.  
  5127.           Declaration: int GetFileMode(char *Filename,int *FMode);
  5128.  
  5129.           Returns:     The return value is 0 if no error occur or the DOS
  5130.                        error code if an error occur.  (See Appendix "A",
  5131.                        FILE FUNCTIONS, for more information).
  5132.  
  5133.           Parameters:
  5134.  
  5135.               Filename - pointer to the file's name.
  5136.  
  5137.                  Fmode - variable that holds the file mode (integer).
  5138.  
  5139.                 The following masks has been defined in SCL1.H:
  5140.  
  5141.                 F_READ_ONLY, F_HIDDEN, F_SYSTEM, F_VOLUME, F_DIRECTORY,
  5142.                 F_ARCHIVE
  5143.  
  5144.           Example:
  5145.  
  5146.           #include <scl1.h>
  5147.  
  5148.           char Filename[]="FILE.1";
  5149.  
  5150.           main()
  5151.           {
  5152.           int handle;
  5153.           unsigned int FMode;
  5154.  
  5155.           if(CreateFile(Filename,&handle,F_ARCHIVE))
  5156.              exit(-1);
  5157.           if(GetFileMode(Filename,&FMode))
  5158.              exit(-1);
  5159.           PrintFMode(FMode);
  5160.           if(SetFileMode(Filename,F_READ_ONLY | F_SYSTEM | F_HIDDEN))
  5161.              exit(-1);
  5162.           if(GetFileMode(Filename,&FMode))
  5163.              exit(-1);
  5164.           PrintFMode(FMode);
  5165.           if(SetFileMode(Filename,F_ARCHIVE))
  5166.              exit(-1);
  5167.           DeleteFile(Filename);
  5168.           }
  5169.  
  5170.  
  5171.                                       Page -83-
  5172.  
  5173.  
  5174.  
  5175.  
  5176.  
  5177.                           SCL1 Version 2.0 Reference Manual
  5178.  
  5179.  
  5180.                                                                 GetFileMode
  5181.  
  5182.           PrintFMode(unsigned int FMode)
  5183.           {
  5184.           printf("\nFile attributtes:\n\n");
  5185.           if(FMode & F_READ_ONLY)
  5186.              printf("\tRead Only\n");
  5187.           if(FMode & F_HIDDEN)
  5188.              printf("\tHidden\n");
  5189.           if(FMode & F_SYSTEM)
  5190.              printf("\tSystem\n");
  5191.           if(FMode & F_ARCHIVE)
  5192.              printf("\tArchive\n");
  5193.           }
  5194.  
  5195.  
  5196.  
  5197.  
  5198.  
  5199.  
  5200.  
  5201.  
  5202.  
  5203.  
  5204.  
  5205.  
  5206.  
  5207.  
  5208.  
  5209.  
  5210.  
  5211.  
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.  
  5219.  
  5220.  
  5221.  
  5222.  
  5223.  
  5224.  
  5225.  
  5226.  
  5227.  
  5228.  
  5229.  
  5230.                                       Page -84-
  5231.  
  5232.  
  5233.  
  5234.  
  5235.  
  5236.                           SCL1 Version 2.0 Reference Manual
  5237.  
  5238.  
  5239.                                                                   GetFilePt
  5240.  
  5241.           Function:    GetFilePt
  5242.  
  5243.           Purpose:     Gets the file's pointer position.
  5244.  
  5245.           Declaration: long GetFilePt(int Handle);
  5246.  
  5247.           Returns:     The file pointer position of the file whose handle
  5248.                        is Handle.  Returns "-1" when a critical error is
  5249.                        detected. (See Appendix "A", FILE FUNCTIONS, for
  5250.                        more information).
  5251.  
  5252.           Parameters:
  5253.  
  5254.                FHandle - Handle returned by DOS when you open or create a
  5255.                          file (integer).
  5256.  
  5257.           Example:
  5258.  
  5259.           #include <scl1.h>
  5260.           #include <string.h>
  5261.  
  5262.              /* This example creates a file with several names in lower-
  5263.              case.  We'll read this file one record at a time into our
  5264.              buffer and convert the string to uppercase before rewriting it
  5265.              back to disk. For simplicity, no error checking is shown in
  5266.              the example */
  5267.  
  5268.           struct NAME_REC{       /* Our file format */
  5269.                char Name[7];
  5270.                }nr;             /* nr will be used as a buffer for
  5271.                                    converting strings to uppercase */
  5272.  
  5273.           /* This is the data of the file we will create */
  5274.  
  5275.           struct NAME_REC names[]={
  5276.              "John",
  5277.              "Mary",
  5278.              "Robert",
  5279.              "Ann"};
  5280.  
  5281.           main()
  5282.              {
  5283.              int handle,i,j;
  5284.              long fileptr,records;
  5285.  
  5286.  
  5287.  
  5288.  
  5289.                                       Page -85-
  5290.  
  5291.  
  5292.  
  5293.  
  5294.  
  5295.                           SCL1 Version 2.0 Reference Manual
  5296.  
  5297.  
  5298.                                                                   GetFilePt
  5299.  
  5300.               /* create file */
  5301.  
  5302.              if(Buf2Disk("DEMO.FL",(char *)names,sizeof(names)))
  5303.                 {
  5304.                 printf("Error creating file\n");
  5305.                 exit(-1);
  5306.                 }
  5307.  
  5308.              /* Open file for reading and writing */
  5309.  
  5310.              OpenFile("DEMO.FL",&handle,DOS2_RW);
  5311.  
  5312.              /* number of records in file = file size / size of structure
  5313.                 NAME_REC */
  5314.  
  5315.              records=GetFileSize(handle)/sizeof(struct NAME_REC);
  5316.  
  5317.              /* read one record at a time while there are records */
  5318.              for(;records > 0;--records)
  5319.                 {
  5320.  
  5321.                 /* save actual file pointer position */
  5322.                 fileptr=GetFilePt(handle);
  5323.  
  5324.                 /* read data, file pointer is automatically moved to next
  5325.                    record by DOS */
  5326.  
  5327.                 ReadFile(handle,(char *)&nr,sizeof(struct NAME_REC));
  5328.  
  5329.                 /* capitalize name */
  5330.                 strupr(nr.Name);
  5331.  
  5332.                 /* move file pointer to original position */
  5333.                 MoveFilePt2Offset(handle,fileptr);
  5334.  
  5335.                 /* write our data, pointer points again to next record */
  5336.                 WriteFile(handle,(char *)&nr,sizeof(struct NAME_REC));
  5337.                 }
  5338.              CloseFile(handle);
  5339.              system("type DEMO.FL");
  5340.              }
  5341.  
  5342.  
  5343.  
  5344.  
  5345.  
  5346.  
  5347.  
  5348.                                       Page -86-
  5349.  
  5350.  
  5351.  
  5352.  
  5353.  
  5354.                           SCL1 Version 2.0 Reference Manual
  5355.  
  5356.  
  5357.                                                                 GetFileSize
  5358.  
  5359.           Function:    GetFileSize
  5360.  
  5361.           Purpose:     Gets the size of the selected file.
  5362.  
  5363.           Declaration: long GetFileSize(int Handle);
  5364.  
  5365.           Returns:     The size of the file whose handle is Handle. 
  5366.                        Returns "-1" when a critical error is detected. (See
  5367.                        Appendix "A", FILE FUNCTIONS, for more information).
  5368.  
  5369.           Parameters:
  5370.  
  5371.                 Handle - Handle returned by DOS when you open or create a
  5372.                          file (integer).
  5373.  
  5374.           Example:
  5375.  
  5376.           #include <scl1.h>
  5377.           #include <string.h>
  5378.  
  5379.              /* This example creates a file with several names in lower-
  5380.              case.  We'll read this file one record at a time into our
  5381.              buffer and convert the string to uppercase before rewriting it
  5382.              back to disk. For simplicity, no error checking is shown in
  5383.              the example */
  5384.  
  5385.           struct NAME_REC{       /* Our file format */
  5386.                char Name[7];
  5387.                }nr;             /* nr will be used as a buffer for
  5388.                                    converting strings to uppercase */
  5389.  
  5390.           /* This is the data of the file we will create */
  5391.  
  5392.           struct NAME_REC names[]={
  5393.              "John",
  5394.              "Mary",
  5395.              "Robert",
  5396.              "Ann"};
  5397.  
  5398.           main()
  5399.              {
  5400.              int handle,i,j;
  5401.              long fileptr,records;
  5402.  
  5403.  
  5404.  
  5405.  
  5406.  
  5407.                                       Page -87-
  5408.  
  5409.  
  5410.  
  5411.  
  5412.  
  5413.                           SCL1 Version 2.0 Reference Manual
  5414.  
  5415.  
  5416.                                                                 GetFileSize
  5417.  
  5418.               /* create file */
  5419.  
  5420.              if(Buf2Disk("DEMO.FL",(char *)names,sizeof(names)))
  5421.                 {
  5422.                 printf("Error creating file\n");
  5423.                 exit(-1);
  5424.                 }
  5425.  
  5426.              /* Open file for reading and writing */
  5427.  
  5428.              OpenFile("DEMO.FL",&handle,DOS2_RW);
  5429.  
  5430.              /* number of records in file = file size / size of structure
  5431.                 NAME_REC */
  5432.  
  5433.              records=GetFileSize(handle)/sizeof(struct NAME_REC);
  5434.  
  5435.              /* read one record at a time while there are records */
  5436.              for(;records > 0;--records)
  5437.                 {
  5438.  
  5439.                 /* save actual file pointer position */
  5440.                 fileptr=GetFilePt(handle);
  5441.  
  5442.                 /* read data, file pointer is automatically moved to next
  5443.                    record by DOS */
  5444.  
  5445.                 ReadFile(handle,(char *)&nr,sizeof(struct NAME_REC));
  5446.  
  5447.                 /* capitalize name */
  5448.                 strupr(nr.Name);
  5449.  
  5450.                 /* move file pointer to original position */
  5451.                 MoveFilePt2Offset(handle,fileptr);
  5452.  
  5453.                 /* write our data, pointer points again to next record */
  5454.                 WriteFile(handle,(char *)&nr,sizeof(struct NAME_REC));
  5455.                 }
  5456.              CloseFile(handle);
  5457.              system("type DEMO.FL");
  5458.              }
  5459.  
  5460.  
  5461.  
  5462.  
  5463.  
  5464.  
  5465.  
  5466.                                       Page -88-
  5467.  
  5468.  
  5469.  
  5470.  
  5471.  
  5472.                           SCL1 Version 2.0 Reference Manual
  5473.  
  5474.  
  5475.                                                                  GetFreeMem
  5476.  
  5477.           Function:    GetFreeMem
  5478.  
  5479.           Purpose:     Gets the free memory reported by the DOS in your
  5480.                        system.
  5481.  
  5482.           Declaration: long GetFreeMem(void);
  5483.  
  5484.           Returns:     The return value is the amount of free memory, in
  5485.                        bytes, reported by the DOS.
  5486.  
  5487.           Parameters:  None
  5488.  
  5489.           Example:
  5490.  
  5491.  
  5492.           #include <scl1.h>
  5493.  
  5494.           main()
  5495.              {
  5496.              printf("Available memory: %li",GetFreeMem());
  5497.              }
  5498.  
  5499.  
  5500.  
  5501.  
  5502.  
  5503.  
  5504.  
  5505.  
  5506.  
  5507.  
  5508.  
  5509.  
  5510.  
  5511.  
  5512.  
  5513.  
  5514.  
  5515.  
  5516.  
  5517.  
  5518.  
  5519.  
  5520.  
  5521.  
  5522.  
  5523.  
  5524.  
  5525.                                       Page -89-
  5526.  
  5527.  
  5528.  
  5529.  
  5530.  
  5531.                           SCL1 Version 2.0 Reference Manual
  5532.  
  5533.  
  5534.                                                                      GetKey
  5535.  
  5536.           Function:    GetKey
  5537.  
  5538.           Purpose:     Waits and returns the pressed key's Scan/ASCII code.
  5539.  
  5540.           Declaration: unsigned int GetKey(void);
  5541.  
  5542.           Returns:     The Scan/Ascii code of the pressed key. See Appendix
  5543.                        "D" for the variables defined in SCL1KEYS.H.
  5544.  
  5545.           Parameters:  None
  5546.  
  5547.           Example:
  5548.  
  5549.           #include <scl1.h>
  5550.           #include <scl1keys.h>
  5551.  
  5552.           main()
  5553.              {
  5554.              unsigned int Key;
  5555.  
  5556.              switch(Key=GetKey())
  5557.                    {
  5558.                    case F1:
  5559.                        .
  5560.                        .
  5561.                    case F2:
  5562.                        .
  5563.                        .
  5564.                    }
  5565.              }
  5566.  
  5567.  
  5568.  
  5569.  
  5570.  
  5571.  
  5572.  
  5573.  
  5574.  
  5575.  
  5576.  
  5577.  
  5578.  
  5579.  
  5580.  
  5581.  
  5582.  
  5583.  
  5584.                                       Page -90-
  5585.  
  5586.  
  5587.  
  5588.  
  5589.  
  5590.                           SCL1 Version 2.0 Reference Manual
  5591.  
  5592.  
  5593.                                                                   GetString
  5594.  
  5595.           Function:    GetString
  5596.  
  5597.           Purpose:     Saves and restores the cursor's size and position,
  5598.                        displays a prompt and the current buffer contents,
  5599.                        positions the cursor and fills the buffer with
  5600.                        keyboard input.  The type and number of characters
  5601.                        are specified. Supports INSERT, DELETE, BACKSPACE,
  5602.                        HOME and END editing keys and mouse input.  If
  5603.                        variable GS_Insert is set to "1" prior to calling
  5604.                        GetString, it will start in the insert mode.  When
  5605.                        no entry has been made into the buffer the variable
  5606.                        GS_Edit is set to "0", otherwise it is set to "1". 
  5607.                        If GS_Beep is set to "1" the console speaker will
  5608.                        sound if an invalid key is pressed.  The buffer must
  5609.                        be initialized with a null terminated string or null
  5610.                        string.
  5611.  
  5612.           Declaration: int GetString(int PColor, int PRow, int PCol,
  5613.                            char* Prompt, int FColor, int FRow, int FCol,
  5614.                            int MaxChar, unsigned int CharType,
  5615.                            char *Buffer);
  5616.  
  5617.           Returns:     Returns the number of characters in buffer or "-1"
  5618.                        if the Esc key is pressed.
  5619.  
  5620.           Parameters:
  5621.  
  5622.                 PColor - color attribute of the prompt (integer).
  5623.  
  5624.                   PRow - row position where to display the prompt
  5625.                          (integer).
  5626.  
  5627.                   PCol - column position where to display the prompt
  5628.                          (integer).
  5629.  
  5630.                 Prompt - pointer to the prompt to be displayed (char).
  5631.  
  5632.                 FColor - color attribute of the field (integer).
  5633.  
  5634.                   FRow - row position where to display the field (integer).
  5635.  
  5636.                   FCol - column position where to display the field
  5637.                          (integer).
  5638.  
  5639.                MaxChar - length of the input field (integer).
  5640.  
  5641.  
  5642.  
  5643.                                       Page -91-
  5644.  
  5645.  
  5646.  
  5647.  
  5648.  
  5649.                           SCL1 Version 2.0 Reference Manual
  5650.  
  5651.  
  5652.                                                                   GetString
  5653.  
  5654.               CharType - the mask of valid characters as described in
  5655.                          function CheckChar. (refer to Appendix "D").
  5656.  
  5657.                 Buffer - pointer to the buffer to be used to store the
  5658.                          field, it must be one digit larger than the
  5659.                          field's size to place the string termination null
  5660.                          character.
  5661.  
  5662.           Example:
  5663.  
  5664.           #include <scl1.h>
  5665.           #include <scl1clor.h>
  5666.  
  5667.           int Color1=BLACK_WHITE;
  5668.           int Color2=WHITE_BLACK;
  5669.  
  5670.           char Buffer[32];
  5671.  
  5672.           main()
  5673.              {
  5674.              GetString(Color1,10,20,"Name:",Color2,10,28,31,CC_ANY,Buffer);
  5675.              }
  5676.  
  5677.  
  5678.  
  5679.  
  5680.  
  5681.  
  5682.  
  5683.  
  5684.  
  5685.  
  5686.  
  5687.  
  5688.  
  5689.  
  5690.  
  5691.  
  5692.  
  5693.  
  5694.  
  5695.  
  5696.  
  5697.  
  5698.  
  5699.  
  5700.  
  5701.  
  5702.                                       Page -92-
  5703.  
  5704.  
  5705.  
  5706.  
  5707.  
  5708.                           SCL1 Version 2.0 Reference Manual
  5709.  
  5710.  
  5711.                                                                     GetTime
  5712.  
  5713.           Function:    GetTime
  5714.  
  5715.           Purpose:     Gets the system time.
  5716.  
  5717.           Declaration: char *GetTime(void);
  5718.  
  5719.           Returns:     The return value is a pointer to a buffer that holds
  5720.                        the system time in ASCII.  Set global variables
  5721.                        GT_Hours, GT_Minutes, GT_Seconds and GT_Hundredths
  5722.                        to the system time.
  5723.  
  5724.           Parameters:  None
  5725.  
  5726.           Example:
  5727.  
  5728.           #include <scl1.h>
  5729.           #include <scl1clor.h>
  5730.  
  5731.           int Color1=BLACK_WHITE;
  5732.  
  5733.           main()
  5734.              {
  5735.              WriteScreen(Color1,3,3,"Time:");
  5736.              WriteScreen(Color1,3,9,GetTime());
  5737.              }
  5738.  
  5739.  
  5740.  
  5741.  
  5742.  
  5743.  
  5744.  
  5745.  
  5746.  
  5747.  
  5748.  
  5749.  
  5750.  
  5751.  
  5752.  
  5753.  
  5754.  
  5755.  
  5756.  
  5757.  
  5758.  
  5759.  
  5760.  
  5761.                                       Page -93-
  5762.  
  5763.  
  5764.  
  5765.  
  5766.  
  5767.                           SCL1 Version 2.0 Reference Manual
  5768.  
  5769.  
  5770.                                                                      GSSBox
  5771.  
  5772.           Function:    GSSBox
  5773.  
  5774.           Purpose:     Draws a box with one of 12 predefined types of
  5775.                        frames. The minimum box size is 2 rows and 2
  5776.                        columns.  The function does not perform bound
  5777.                        checking, the box will spill out of the desired area
  5778.                        if the coordinates are outside the screen range. 
  5779.                        The function draws a box frame and fills its
  5780.                        interior.  Three flags; Grow, Noise and Shadow can
  5781.                        be specified.  The grow flag signals the function to
  5782.                        draw the box with a growing effect, the noise flag
  5783.                        signals the function to make a swirling noise when
  5784.                        drawing the box, and the shadow flag signals the
  5785.                        function to add a shadow effect.  If you do not
  5786.                        specify a shadow color (using the SetShadowColor
  5787.                        function) it will be XOR'ed to the current
  5788.                        background color.  Make sure to leave space for the
  5789.                        shadow characters.  You can define other types of
  5790.                        frames using the SetUserBox function.
  5791.  
  5792.           Declaration: void GSSBox(int Color, int FrameType,
  5793.                             int UpperRow, int LeftCol, int LowerRow,
  5794.                             int RightCol,int GrowFl,int SoundFl,
  5795.                             int ShadowFl);
  5796.  
  5797.           Returns:     Nothing
  5798.  
  5799.           Parameters:
  5800.  
  5801.                  Color - color attribute for the box (integer).
  5802.  
  5803.              FrameType - frame type, an integer value from 0 to 11 as
  5804.                          follows, box frame 12 draws the user defined
  5805.                          frame:
  5806.  
  5807.                ╔═════════╗ ┌─────────┐ ╓─────────╖ ╒═════════╕  ╒════════╕
  5808.                ║ FRAME 0 ║ │ FRAME 1 │ ║ FRAME 2 ║ │ FRAME 3 │  │ FRAME 4│
  5809.                ╚═════════╝ └─────────┘ ╙─────────╜ ╘═════════╛  └────────┘
  5810.  
  5811.                            ▄▄▄▄▄▄▄▄▄▄  ░░░░░░░░░░░  ▒▒▒▒▒▒▒▒▒▒  ▓▓▓▓▓▓▓▓▓▓
  5812.                  FRAME 5   ▌ FRAME 6▐  ░ FRAME 7 ░  ▒FRAME 8 ▒  ▓FRAME 9 ▓
  5813.                            ▀▀▀▀▀▀▀▀▀▀  ░░░░░░░░░░░  ▒▒▒▒▒▒▒▒▒▒  ▓▓▓▓▓▓▓▓▓▓
  5814.  
  5815.                ██████████  **********
  5816.                █FRAME 10█  *FRAME 11*
  5817.                ██████████  **********
  5818.  
  5819.  
  5820.                                       Page -94-
  5821.  
  5822.  
  5823.  
  5824.  
  5825.  
  5826.                           SCL1 Version 2.0 Reference Manual
  5827.  
  5828.  
  5829.                                                                      GSSBox
  5830.  
  5831.              (Note: You will not be able to print the correct frame types
  5832.              if your printer does not support the IBM extended ASCII
  5833.              character set.)
  5834.  
  5835.               UpperRow - upper row coordinate of the box (integer).
  5836.  
  5837.                LeftCol - left column coordinate of the box (integer).
  5838.  
  5839.               LowerRow - lower row coordinate of the box (integer).
  5840.  
  5841.               RightCol - right column coordinate of the box (integer).
  5842.  
  5843.              (Note: the home position is row 0, column 0.)
  5844.  
  5845.  
  5846.                 GrowFl - flag to signal a growing box.  If this value is
  5847.                          "1" the box will grow from its center out.  If the
  5848.                          value is "0" the box will pop into the screen
  5849.                          (integer).
  5850.  
  5851.                SoundFl - flag to signal a noise growing box. If the value
  5852.                          is "1" when the box grows it will make a swirling
  5853.                          noise.  A value of "0" will draw a quiet box
  5854.                          (integer).
  5855.  
  5856.               ShadowFl - flag to signal a shadow effect.  If the value is
  5857.                          "1" a shadow effect will be drawn, if the value is
  5858.                          "0" no shadow effect will be drawn. The shadow
  5859.                          will be XOR'ed to the background, if no shadow
  5860.                          color have been defined (integer).
  5861.  
  5862.           Example:
  5863.  
  5864.           #include <scl1.h>
  5865.           #include <scl1clor.h>
  5866.  
  5867.           int Color1=WHITE_BLACK;
  5868.  
  5869.           main()
  5870.              {
  5871.              GSSBox(Color19,0,3,12,20,68,1,1,0);
  5872.              /* Will draw a growing, shadowed, double framed box between
  5873.                 rows 3 & 20 and columns 12 & 68 */
  5874.              }
  5875.  
  5876.           See also Box, Shadow, SetShadowColor, SetUserFrame.
  5877.  
  5878.  
  5879.                                       Page -95-
  5880.  
  5881.  
  5882.  
  5883.  
  5884.  
  5885.                           SCL1 Version 2.0 Reference Manual
  5886.  
  5887.  
  5888.                                                                   HideMouse
  5889.  
  5890.           Function:    HideMouse
  5891.  
  5892.           Purpose:     Hides or removes the mouse cursor from the screen.
  5893.  
  5894.           Declaration: void HideMouse(void);
  5895.  
  5896.           Returns:     Nothing
  5897.  
  5898.           Parameters:  None
  5899.  
  5900.           Example:
  5901.  
  5902.           #include <scl1.h>
  5903.  
  5904.           main()
  5905.              {
  5906.              InitMouse(IM_SHOW); /* initialize mouse, turn cursor on */
  5907.  
  5908.              if(MSE_MouseFl)
  5909.                 {
  5910.                 printf("We have a mouse, click the left button to turn
  5911.                         mouse cursor off.\n");
  5912.                 WaitKeyMouse();
  5913.                 HideMouse();
  5914.                 printf("Click again to turn mouse cursor on.\n");
  5915.                 WaitKeyMouse();
  5916.                 ShowMouse();
  5917.                 printf("Click to exit.\n");
  5918.                 WaitKeyMouse();
  5919.                 }
  5920.              else
  5921.                 printf("We don't have a mouse\n");
  5922.              }
  5923.           }
  5924.  
  5925.  
  5926.  
  5927.  
  5928.  
  5929.  
  5930.  
  5931.  
  5932.  
  5933.  
  5934.  
  5935.  
  5936.  
  5937.  
  5938.                                       Page -96-
  5939.  
  5940.  
  5941.  
  5942.  
  5943.  
  5944.                           SCL1 Version 2.0 Reference Manual
  5945.  
  5946.  
  5947.                                                                   InitMouse
  5948.  
  5949.           Function:    InitMouse
  5950.  
  5951.           Purpose:     Initializes the mouse for further use of the mouse
  5952.                        functions.  When you exit the program it takes care
  5953.                        of resetting the mouse.
  5954.  
  5955.           Declaration: int InitMouse(int Cursor);
  5956.  
  5957.           Returns:     Returns "-1" if an error has occurred that prevents
  5958.                        the function to initialize the mouse correctly.
  5959.  
  5960.           Parameters:
  5961.  
  5962.                 Cursor - this parameter tells InitMouse how to handle the
  5963.                          mouse cursor.  The following variables have been
  5964.                          defined in SCL1.H;
  5965.  
  5966.                            IM_SHOW - means to the show mouse cursor
  5967.                                      (integer).
  5968.  
  5969.                         IM_NO_SHOW - means not to show the mouse cursor
  5970.                                      (integer).
  5971.  
  5972.           Example:
  5973.  
  5974.           #include <scl1.h>
  5975.  
  5976.           main()
  5977.              {
  5978.              InitMouse(IM_SHOW); /* initialize mouse, turn cursor on */
  5979.  
  5980.              if(MSE_MouseFl)
  5981.                 {
  5982.                 printf("We have a mouse, click the left button to turn
  5983.                         mouse cursor off.\n");
  5984.                 WaitKeyMouse();
  5985.                 HideMouse();
  5986.                 printf("Click again to turn mouse cursor on.\n");
  5987.                 WaitKeyMouse();
  5988.                 ShowMouse();
  5989.                 printf("Click to exit.\n");
  5990.                 WaitKeyMouse();
  5991.                 }
  5992.              else
  5993.                 printf("We don't have a mouse\n");
  5994.              }
  5995.  
  5996.  
  5997.                                       Page -97-
  5998.  
  5999.  
  6000.  
  6001.  
  6002.  
  6003.                           SCL1 Version 2.0 Reference Manual
  6004.  
  6005.  
  6006.                                                               InitUserError
  6007.  
  6008.           Function:    InitUserError
  6009.  
  6010.           Purpose:     Initialize user defined error codes for use with the
  6011.                        ErrorBox function.  You can redefine the standard
  6012.                        error messages included in ErrorBox.
  6013.  
  6014.           Declaration: void InitUserError(struct ErrorMess *p);
  6015.  
  6016.           Returns:     Nothing
  6017.  
  6018.           Parameters:
  6019.  
  6020.           The Error Message information is placed in an array of structures
  6021.           as follows: (The array of structures must be terminated with a
  6022.           "0").
  6023.  
  6024.              struct ErrorMess{
  6025.                 int ErrorNum;
  6026.                 char *Message;
  6027.                 };
  6028.  
  6029.           where,
  6030.  
  6031.               ErrorNum - user defined error number, an integer value above
  6032.                          256 (integer).  If a predefined error message is
  6033.                          initialized, the function will use the new values. 
  6034.                          This permits to change the error messages.
  6035.  
  6036.                Message - pointer to the user defined error message's text.
  6037.  
  6038.  
  6039.           Example:
  6040.  
  6041.           #include <scl1.h>
  6042.  
  6043.           struct ErrorMess em[]={
  6044.              256,"Please type either Y for YES\nor N for NO",
  6045.              0};
  6046.  
  6047.           main()
  6048.              {
  6049.              int Key;
  6050.  
  6051.              InitUserError(em);
  6052.              printf("\nInstall printer driver? (Y/N)\n");
  6053.  
  6054.  
  6055.  
  6056.                                       Page -98-
  6057.  
  6058.  
  6059.  
  6060.  
  6061.  
  6062.                           SCL1 Version 2.0 Reference Manual
  6063.  
  6064.  
  6065.                                                               InitUserError
  6066.  
  6067.              do
  6068.                 {
  6069.                 Key=toupper(getch());
  6070.                 if(Key != 'Y' && Key != 'N')
  6071.                    ErrorBox(256);
  6072.                 else
  6073.                    break;
  6074.                 }while(1);
  6075.              }
  6076.  
  6077.           See also ErrorBox, ErrorShadowOff, ErrorShadowOn and
  6078.           SetErrorBoxColor.
  6079.  
  6080.  
  6081.  
  6082.  
  6083.  
  6084.  
  6085.  
  6086.  
  6087.  
  6088.  
  6089.  
  6090.  
  6091.  
  6092.  
  6093.  
  6094.  
  6095.  
  6096.  
  6097.  
  6098.  
  6099.  
  6100.  
  6101.  
  6102.  
  6103.  
  6104.  
  6105.  
  6106.  
  6107.  
  6108.  
  6109.  
  6110.  
  6111.  
  6112.  
  6113.  
  6114.  
  6115.                                       Page -99-
  6116.  
  6117.  
  6118.  
  6119.  
  6120.  
  6121.                           SCL1 Version 2.0 Reference Manual
  6122.  
  6123.  
  6124.                                                                   InitVideo
  6125.  
  6126.           Function:    InitVideo
  6127.  
  6128.           Purpose:     Initialize video monitor to the alphanumeric display
  6129.                        mode.
  6130.  
  6131.           Declaration: void InitVideo (void);
  6132.  
  6133.           Returns:     Nothing
  6134.  
  6135.           Parameters:  None
  6136.  
  6137.           Example:
  6138.  
  6139.           #include <scl1.h>
  6140.  
  6141.           main()
  6142.              {
  6143.              InitVideo();
  6144.              printf("SCL1's InitVideo function has initialized your
  6145.                      monitor\nto it's default alphanumeric mode.\n");
  6146.              }
  6147.  
  6148.  
  6149.  
  6150.  
  6151.  
  6152.  
  6153.  
  6154.  
  6155.  
  6156.  
  6157.  
  6158.  
  6159.  
  6160.  
  6161.  
  6162.  
  6163.  
  6164.  
  6165.  
  6166.  
  6167.  
  6168.  
  6169.  
  6170.  
  6171.  
  6172.  
  6173.  
  6174.                                      Page -100-
  6175.  
  6176.  
  6177.  
  6178.  
  6179.  
  6180.                           SCL1 Version 2.0 Reference Manual
  6181.  
  6182.  
  6183.                                                              Int24ShadowOff
  6184.                                                               Int24ShadowOn
  6185.  
  6186.           Function:    Int24ShadowOff
  6187.                        Int24ShadowOn
  6188.  
  6189.           Purpose:     Enable or disable a shadow effect when using the
  6190.                        TrapInt24 function.  After any of these functions is
  6191.                        called, all TrapInt24 messages will be displayed
  6192.                        with (or without) a shadow effect.
  6193.  
  6194.           Declaration: void Int24ShadowOff(void);
  6195.                        void Int24ShadowOn(void);
  6196.  
  6197.           Returns:     Nothing.
  6198.  
  6199.           Parameters:  None.
  6200.  
  6201.           Example:
  6202.  
  6203.  
  6204.              Int24ShadowOff(); /* Turn off shadow effect on error boxes */
  6205.              Int24ShadowOn();  /* Turn on shadow effect on error boxes  */
  6206.  
  6207.  
  6208.           See TrapInt24 and SetTrapInt24Colors.
  6209.  
  6210.  
  6211.  
  6212.  
  6213.  
  6214.  
  6215.  
  6216.  
  6217.  
  6218.  
  6219.  
  6220.  
  6221.  
  6222.  
  6223.  
  6224.  
  6225.  
  6226.  
  6227.  
  6228.  
  6229.  
  6230.  
  6231.  
  6232.  
  6233.                                      Page -101-
  6234.  
  6235.  
  6236.  
  6237.  
  6238.  
  6239.                           SCL1 Version 2.0 Reference Manual
  6240.  
  6241.  
  6242.                                                                    KeyReady
  6243.  
  6244.           Function:    KeyReady
  6245.  
  6246.           Purpose:     Scans the BIOS keyboard buffer for unprocessed
  6247.                        keystrokes.
  6248.  
  6249.           Declaration: unsigned int KeyReady(void);
  6250.  
  6251.           Returns:     Return the Scan/Ascii code of key in the BIOS buffer
  6252.                        or "0" if it is empty.
  6253.  
  6254.           Parameters:  None
  6255.  
  6256.           Example:
  6257.  
  6258.           #include <scl1.h>
  6259.  
  6260.           main()
  6261.              {
  6262.              while(!KeyReady())
  6263.                 printf("No key has been pressed!\n");
  6264.              ClearKeyBuf();
  6265.              }
  6266.  
  6267.  
  6268.  
  6269.  
  6270.  
  6271.  
  6272.  
  6273.  
  6274.  
  6275.  
  6276.  
  6277.  
  6278.  
  6279.  
  6280.  
  6281.  
  6282.  
  6283.  
  6284.  
  6285.  
  6286.  
  6287.  
  6288.  
  6289.  
  6290.  
  6291.  
  6292.                                      Page -102-
  6293.  
  6294.  
  6295.  
  6296.  
  6297.  
  6298.                           SCL1 Version 2.0 Reference Manual
  6299.  
  6300.  
  6301.                                                                   KeyStatus
  6302.  
  6303.           Function:    KeyStatus
  6304.  
  6305.           Purpose:     Returns the shift, control and toggle key status.
  6306.  
  6307.           Declaration: unsigned char KeyStatus(void);
  6308.  
  6309.           Returns:     The return value AND the following masks, defined in
  6310.                        SCL1.H, are ">0" if the key is toggled or pressed.
  6311.  
  6312.                        The mask values defined in SCL1.H are: INSERT,
  6313.                        CAPSL, NUMSL, SCROLL, ALT, CTRL, LSHIFT and RSHIFT.
  6314.  
  6315.           Example:
  6316.  
  6317.           #include <scl1.h>
  6318.           #include <scl1keys.h>
  6319.           #include <scl1clor.h>
  6320.  
  6321.           int Color1=BLACK_WHITE;
  6322.           int Color2=WHITE_BLACK;
  6323.  
  6324.           main()
  6325.              {
  6326.              unsigned int Key;
  6327.  
  6328.              Key=KeyStatus();
  6329.              if (Key&ALT)                    /* ALT key pressed */
  6330.                 WriteScreen(Color1,17,10,"Pressed    ");
  6331.              else
  6332.                 WriteScreen(Color2,17,10,"Not Pressed");
  6333.  
  6334.              if (Key&INSERT)                 /* INSERT mode is on */
  6335.                 WriteScreen(Color1,17,34,"On ");
  6336.              else
  6337.                 WriteScreen(Color2,17,34,"Off");
  6338.              }
  6339.  
  6340.  
  6341.  
  6342.  
  6343.  
  6344.  
  6345.  
  6346.  
  6347.  
  6348.  
  6349.  
  6350.  
  6351.                                      Page -103-
  6352.  
  6353.  
  6354.  
  6355.  
  6356.  
  6357.                           SCL1 Version 2.0 Reference Manual
  6358.  
  6359.  
  6360.                                                                  LineEditor
  6361.  
  6362.           Function:    LineEditor
  6363.  
  6364.           Purpose:     A full featured line editor.  You can define all the
  6365.                        parameters required for the line editor such as;
  6366.                        where to display a prompt, size of the field, size
  6367.                        of the display, colors, cursor size, default editing
  6368.                        mode, etc.
  6369.  
  6370.           Declaration: int LineEditor(int Message,LEData *p,...);
  6371.  
  6372.           Returns:     This is a dialog type function. See Appendix "E" for
  6373.                        a description of the general operation of these
  6374.                        functions.  The return value is a message described
  6375.                        in the Messages section.
  6376.  
  6377.           Parameters:
  6378.  
  6379.           The line editor information must be given in a structure defined
  6380.           as type LEData. The structure elements are as follows:
  6381.  
  6382.           typedef struct{
  6383.              int PColor;
  6384.              int PRow;
  6385.              int PCol;
  6386.              char *Prompt;
  6387.              int FColor;
  6388.              int FRow;
  6389.              int FCol;
  6390.              unsigned int FLength;
  6391.              unsigned int FSize;
  6392.              int CType;
  6393.              int MaskFn;
  6394.              char *MaskArray;
  6395.              char *Buffer;
  6396.              char *FormatC;
  6397.              unsigned int *ExitKeys;
  6398.              int InsFlag;
  6399.              int InsertCur;
  6400.              int TypeOverCur;
  6401.              int CPaint;
  6402.              unsigned int StartPos;
  6403.              unsigned int EndPos;
  6404.              unsigned int EventInfo;
  6405.              unsigned int Position;
  6406.              unsigned int Scroll;
  6407.              int Edited;
  6408.              }LEData;
  6409.  
  6410.                                      Page -104-
  6411.  
  6412.  
  6413.  
  6414.  
  6415.  
  6416.                           SCL1 Version 2.0 Reference Manual
  6417.  
  6418.  
  6419.                                                                  LineEditor
  6420.  
  6421.           where,
  6422.  
  6423.                 PColor - color attribute for the prompt (integer).
  6424.  
  6425.                    Row - row position where to display the for the prompt's
  6426.                          display (integer).
  6427.  
  6428.                   PCol - column position for the prompt's display
  6429.                          (integer).
  6430.  
  6431.                 Prompt - char pointer to the prompt.
  6432.  
  6433.                 FColor - color attribute for the field (integer).
  6434.  
  6435.                   FRow - row position for the field's display (integer).
  6436.  
  6437.                   FCol - column position for the field's display (integer).
  6438.  
  6439.                FLength - field's display length.  Number of characters to
  6440.                          display.  If the field size is larger than the
  6441.                          display size, the length of the display line for
  6442.                          the field (unsigned integer).
  6443.  
  6444.                 FSize -  maximum number of characters of the field. This
  6445.                          number can be larger than the field length, in
  6446.                          which case, the display will scroll horizontally
  6447.                          when the cursor reaches the end of the available
  6448.                          display length (unsigned integer).
  6449.  
  6450.                  CType - type of characters to be accepted. Please refer to 
  6451.                          CheckChar for a description of the values defined
  6452.                          in SCL1.H (integer).
  6453.  
  6454.                 MaskFn - a flag to instruct the function to accept or
  6455.                          discard the characters defined in the MaskArray
  6456.                          array.  A value of 0 will accept the characters
  6457.                          and a value of 1 will discard them (integer).
  6458.  
  6459.              MaskArray - array of mask characters (null terminated).
  6460.  
  6461.                 Buffer - buffer that holds the information to be edited.
  6462.  
  6463.                FormatC - a string that holds the characters to be used as
  6464.                          format characters during editing.
  6465.  
  6466.               ExitKeys - null terminated array of unsigned integer
  6467.                          Scan/Ascii values of the keys to exit.
  6468.  
  6469.                                      Page -105-
  6470.  
  6471.  
  6472.  
  6473.  
  6474.  
  6475.                           SCL1 Version 2.0 Reference Manual
  6476.  
  6477.  
  6478.                                                                  LineEditor
  6479.  
  6480.                InsFlag - a flag to instruct the function of the default
  6481.                          edit mode. ("1" = Insert,"0" = typeover)(integer).
  6482.  
  6483.              InsertCur - size of cursor when insert mode is toggled ("0" =
  6484.                          no cursor, "1" = normal cursor, "2" = block sized
  6485.                          cursor)(integer).
  6486.  
  6487.            TypeOverCur - size of cursor when typeover mode is toggled ("0"=
  6488.                          no cursor, "1" = normal cursor, "2" = block sized
  6489.                          cursor)(integer).
  6490.  
  6491.                 CPaint - color to be used to mark a group of characters
  6492.                          from the position defined by StartPos to EndPos.
  6493.                          The CPaint value can be used to construct
  6494.                          character blocks (integer).
  6495.  
  6496.               StartPos - start position of conditional paint characters
  6497.                          (unsigned integer).
  6498.  
  6499.                 EndPos - end position of conditional paint characters
  6500.                          (unsigned integer).
  6501.  
  6502.              EventInfo - information about the keys that have been pressed
  6503.                          (unsigned integer).
  6504.  
  6505.               Position - contains the current cursor position within the
  6506.                          buffer (or offset)(unsigned integer).
  6507.  
  6508.                 Scroll - horizontal scroll counter, keeps track of the
  6509.                          cursor position when the field size is larger than
  6510.                          the field length.
  6511.  
  6512.                 Edited - a flag that keeps track of the field activity.  A
  6513.                          value of "0" means that the field has not been
  6514.                          edited and a value of "1" means that the field has
  6515.                          been edited (integer).
  6516.  
  6517.  
  6518.  
  6519.  
  6520.  
  6521.  
  6522.  
  6523.  
  6524.  
  6525.  
  6526.  
  6527.  
  6528.                                      Page -106-
  6529.  
  6530.  
  6531.  
  6532.  
  6533.  
  6534.                           SCL1 Version 2.0 Reference Manual
  6535.  
  6536.  
  6537.                                                                  LineEditor
  6538.  
  6539.           Messages:
  6540.  
  6541.           Messages that can be sent to the LineEditor function:
  6542.  
  6543.                      LE_INIT - Initialize the LEData structure to NULL and
  6544.                                sets the following default values:
  6545.  
  6546.                             PColor - set to white characters in a black
  6547.                                      background or the normal color defined
  6548.                                      by calling SetDialogColors.
  6549.  
  6550.                             FColor - set to black characters in a white
  6551.                                      background or the reversed color
  6552.                                      defined by calling SetDialogColors.
  6553.  
  6554.                            FLength - set to 40 columns.
  6555.  
  6556.                              FSize - set to 40 columns.
  6557.  
  6558.                              CType - set to CC_ANY, accept any character.
  6559.  
  6560.                             Buffer - set to use a default internal buffer
  6561.                                      called DefBuf.
  6562.  
  6563.                           ExitKeys - set to the default exit keys.
  6564.  
  6565.                            InsFlag - set to the typeover mode.
  6566.  
  6567.                          InsertCur - set to a value of "2".
  6568.  
  6569.                      LE_DRAW - display the prompt and current edit buffer's
  6570.                                information.
  6571.  
  6572.              LE_UPDATE_FIELD - display the current edit buffer's contents.
  6573.  
  6574.  
  6575.  
  6576.  
  6577.  
  6578.  
  6579.  
  6580.  
  6581.  
  6582.  
  6583.  
  6584.  
  6585.  
  6586.  
  6587.                                      Page -107-
  6588.  
  6589.  
  6590.  
  6591.  
  6592.  
  6593.                           SCL1 Version 2.0 Reference Manual
  6594.  
  6595.  
  6596.                                                                  LineEditor
  6597.  
  6598.                    LE_ACTIVE - edit the contents of the field buffer. The
  6599.                                following edit keys have been defined:
  6600.  
  6601.                          Key                      Action
  6602.  
  6603.                        Left Arrow       cursor one position to the left.
  6604.                        Right Arrow      cursor one position to the right.
  6605.                        END              cursor to end of field.
  6606.                        HOME             cursor to beginning of field.
  6607.                        INSERT           toggle insert mode on/off.
  6608.                        BACKSPACE        erase the character at current
  6609.                                         cursor position. Move remaining
  6610.                                         text to the left.
  6611.  
  6612.                       LE_KEY - the parameter passed with this messages
  6613.                                (Scan+Ascii code of the key) is a control
  6614.                                key value that performs as if the control
  6615.                                key has been pressed.
  6616.  
  6617.                      LE_DATA - the parameter passed with this messages is
  6618.                                an ASCII key value that performs as if that
  6619.                                character has been typed.
  6620.  
  6621.            LE_POSITION_BEGIN - move cursor the start of the edit buffer.
  6622.  
  6623.              LE_POSITION_END - move cursor to the end of the edit buffer.
  6624.  
  6625.               LE_POSITION_UP - move cursor one position forward.
  6626.  
  6627.             LE_POSITION_DOWN - move cursor one position backwards.
  6628.  
  6629.              LE_SET_POSITION - set the cursor position.
  6630.  
  6631.                  LE_CHARS_UP - moves all the text from the current cursor
  6632.                                position one space forward.
  6633.  
  6634.                LE_CHARS_DOWN - moves all the text in the field from the
  6635.                                current cursor position one space backwards.
  6636.  
  6637.  
  6638.  
  6639.  
  6640.  
  6641.  
  6642.  
  6643.  
  6644.  
  6645.  
  6646.                                      Page -108-
  6647.  
  6648.  
  6649.  
  6650.  
  6651.  
  6652.                           SCL1 Version 2.0 Reference Manual
  6653.  
  6654.  
  6655.                                                                  LineEditor
  6656.  
  6657.                     LE_CLEAR - clear the editor's buffer.
  6658.  
  6659.                     LE_RESET - when this message is sent the field contents
  6660.                                variables are reset to the default value. 
  6661.                                If the exit keys have not been defined they
  6662.                                are set to the default exit keys.
  6663.  
  6664.           Messages that LineEditor can return:
  6665.  
  6666.                        LE_OK - the requested action has been successfully
  6667.                                performed.
  6668.  
  6669.                  LE_EXIT_KEY - a key defined as an exit key has been
  6670.                                pressed.
  6671.  
  6672.               LE_MOUSE_EVENT - the mouse has been clicked after pointing
  6673.                                outside the Line Editor field.
  6674.  
  6675.                LE_BUFFER_END - you have reached the buffer's maximum size.
  6676.  
  6677.              LE_BUFFER_BEGIN - you have reached the beginning of the edit
  6678.                                buffer.
  6679.  
  6680.               LE_ILLEGAL_KEY - a key that has not been defined as an exit
  6681.                                key or that is not a legal key as defined
  6682.                                for that field has been pressed.
  6683.  
  6684.               LE_BUFFER_FULL - the edit buffer is full.
  6685.  
  6686.           LE_ILLEGAL_POSITION- you have requested to move the cursor passed
  6687.                                the maximum defined field length or left of
  6688.                                the beginning position.
  6689.  
  6690.              LE_NEW_POSITION - a legal editing function is performed.
  6691.  
  6692.                  LE_MY_MOUSE - response to a LE_CHECK_MOUSE message if the
  6693.                                mouse has been clicked after pointing to the
  6694.                                field area defined by the function.
  6695.  
  6696.                  LE_DEL_NULL - you have pressed the delete key when the
  6697.                                cursor has reached the buffer end.
  6698.  
  6699.           Example:
  6700.  
  6701.           #include <scl1.h>
  6702.           #include <scl1keys.h>
  6703.           #include <scl1clor.h>
  6704.  
  6705.                                      Page -109-
  6706.  
  6707.  
  6708.  
  6709.  
  6710.  
  6711.                           SCL1 Version 2.0 Reference Manual
  6712.  
  6713.  
  6714.                                                                  LineEditor
  6715.  
  6716.           unsigned int ExitKeys[]={ENTER,ESC,0};
  6717.  
  6718.           main()
  6719.           {
  6720.           LEData led;
  6721.           int Mess;
  6722.           char buffer[81];
  6723.  
  6724.           Cls(WHITE_BLACK,CLS_ALL);               /* clear screen */
  6725.           memset(buffer,0,sizeof(buffer));        /* initialize buffer */
  6726.  
  6727.              /* initialize Line Editor structure */
  6728.  
  6729.           LineEditor(LE_INIT,&led);
  6730.  
  6731.              /* modify prompt and field position */
  6732.  
  6733.           led.PRow=led.FRow=12;
  6734.           led.PCol=25;
  6735.           led.FCol=35;
  6736.  
  6737.              /* the field's screen length is of 20 characters but up to
  6738.                 80 characters can be entered, the data entry field will
  6739.                 scroll automatically */
  6740.  
  6741.           led.FLength=20;
  6742.           led.FSize=80;
  6743.  
  6744.           led.Prompt="Filename:";            /* prompt */
  6745.           led.CType=CC_PATH | CC_CAPITALIZE; /* type of valid characters */
  6746.           led.Buffer=buffer;                 /* use our buffer */
  6747.           led.ExitKeys=ExitKeys;             /* our defined exit keys */
  6748.           PushCursor();                      /* save cursor */
  6749.           LineEditor(LE_DRAW,&led);          /* draw */
  6750.  
  6751.              /* Main loop: send ACTIVE message,
  6752.                 LineEditor constantly returns information */
  6753.           do
  6754.              {
  6755.              Mess=LineEditor(LE_ACTIVE,&led);
  6756.              if(Mess==LE_ILLEGAL_KEY)        /* illegal key? */
  6757.                 TSound(440,10);              /* beep */
  6758.  
  6759.              /* loop until an exit key is pressed */
  6760.              }while(Mess != LE_EXIT_KEY);
  6761.           PopCursor();
  6762.           }
  6763.  
  6764.                                      Page -110-
  6765.  
  6766.  
  6767.  
  6768.  
  6769.  
  6770.                           SCL1 Version 2.0 Reference Manual
  6771.  
  6772.  
  6773.                                                                 ListManager
  6774.  
  6775.           Function:    ListManager
  6776.  
  6777.           Purpose:     Displays a list of items and permits user selection
  6778.                        of items.  Mouse input is supported.
  6779.  
  6780.           Declaration: int ListManager(int NColor, int RColor,int Number,
  6781.                             int Length,int Selection, int Lines,
  6782.                             int Cols, struct ItemList*p);
  6783.  
  6784.           Returns:     The return value is the number of the selected item.
  6785.  
  6786.           Parameters:
  6787.  
  6788.           The Item List message information must be given as an array of
  6789.           structures as follows:
  6790.  
  6791.              struct ItemList{
  6792.                 int Row,Col;
  6793.                 char *String;
  6794.                 };
  6795.  
  6796.           where,
  6797.  
  6798.                    Row - row position of where to display the item
  6799.                          (integer).
  6800.  
  6801.                    Col - column position where to display the item
  6802.                          (integer).
  6803.  
  6804.                 String - char pointer to the item text to be displayed.
  6805.  
  6806.           The parameters passed to the function are:
  6807.  
  6808.                 NColor - color attribute for the normal display of items
  6809.                          (integer).
  6810.  
  6811.                 RColor - color attribute for the highlighted item
  6812.                          (integer).
  6813.  
  6814.                 Number - number of items defined (integer).
  6815.  
  6816.                 Length - length of the items (integer).
  6817.  
  6818.              Selection - default selection (integer).
  6819.  
  6820.                  Lines - number of lines to be displayed (integer).
  6821.  
  6822.  
  6823.                                      Page -111-
  6824.  
  6825.  
  6826.  
  6827.  
  6828.  
  6829.                           SCL1 Version 2.0 Reference Manual
  6830.  
  6831.  
  6832.                                                                 ListManager
  6833.  
  6834.                   Cols - number of columns to be displayed (integer).
  6835.  
  6836.               ItemList - pointer to the item list structure.
  6837.  
  6838.           Example:
  6839.  
  6840.  
  6841.           #include <scl1.h>
  6842.           #include <scl1clor.h>
  6843.  
  6844.           int Color1=BLACK_WHITE;
  6845.           int Color2=WHITE_BLACK;
  6846.  
  6847.           struct ItemList il[]={
  6848.              10,10,"Item #1",
  6849.              10,20,"Item #2",
  6850.              10,30,"Item #3",
  6851.              12,10,"Item #4",
  6852.              12,20,"Item #5",
  6853.              12,30,"Item #6",
  6854.              };
  6855.  
  6856.           main()
  6857.              {
  6858.              int ItemSelected;
  6859.  
  6860.              ItemSelected=ListManager(Color1,Color2,6,6,1,2,3,il);
  6861.              }
  6862.  
  6863.           See also ListWindow.
  6864.  
  6865.  
  6866.  
  6867.  
  6868.  
  6869.  
  6870.  
  6871.  
  6872.  
  6873.  
  6874.  
  6875.  
  6876.  
  6877.  
  6878.  
  6879.  
  6880.  
  6881.  
  6882.                                      Page -112-
  6883.  
  6884.  
  6885.  
  6886.  
  6887.  
  6888.                           SCL1 Version 2.0 Reference Manual
  6889.  
  6890.  
  6891.                                                                  ListWindow
  6892.  
  6893.           Function:    ListWindow
  6894.  
  6895.           Purpose:     Displays an array of items in a window in columnar
  6896.                        format.  The user can use the arrow keys or the
  6897.                        mouse to tag or select a desired item.  When the
  6898.                        list of items is large, the function displays scroll
  6899.                        bars to let the user know that there are items not
  6900.                        shown in the window.
  6901.  
  6902.           Declaration: int ListWindow(int Message,LWData *p,...);
  6903.  
  6904.           Returns:     This is a dialog type function. See Appendix "E" for
  6905.                        a description of the general operation of these
  6906.                        functions.  The return value is a message described
  6907.                        in the Messages section.
  6908.  
  6909.           Parameters:
  6910.  
  6911.           The list window information must be given in a structure defined
  6912.           as type LWData. The structure elements are as follows:
  6913.  
  6914.           LWData structure:
  6915.  
  6916.           typedef struct{
  6917.              int NColor;
  6918.              int RColor;
  6919.              int UpperRow;
  6920.              int LeftCol;
  6921.              int LowerRow;
  6922.              int RightCol;
  6923.              int FrameType;
  6924.              int ScrollBar;
  6925.              int BarColor;
  6926.              char **Array;
  6927.              char *TagArray;
  6928.              int TagColor;
  6929.              char *Title;
  6930.              int TitleColor;
  6931.              unsigned int *ExitKeys;
  6932.              int StaticWidth;
  6933.              unsigned int Items;
  6934.              unsigned int ColumnWidth;
  6935.              unsigned int FirstItem;
  6936.              unsigned int Position;
  6937.              unsigned int *ExitKeys;
  6938.              int WindowLines;
  6939.              int WindowCols;
  6940.  
  6941.                                      Page -113-
  6942.  
  6943.  
  6944.  
  6945.  
  6946.  
  6947.                           SCL1 Version 2.0 Reference Manual
  6948.  
  6949.  
  6950.                                                                  ListWindow
  6951.  
  6952.              int TotalCols;
  6953.              int TotalWindowItems;
  6954.              int OldHBlock;
  6955.              unsigned int EventInfo;
  6956.              }LWData;
  6957.  
  6958.           where,
  6959.  
  6960.                       NColor - color attribute for normal display
  6961.                                (integer).
  6962.  
  6963.                       RColor - color attributes for reversed display
  6964.                                (integer).
  6965.  
  6966.                     UpperRow - upper row coordinate of the window
  6967.                                (integer).
  6968.  
  6969.                      LeftCol - left column coordinate of the window
  6970.                                (integer).
  6971.  
  6972.                     LowerRow - lower row coordinate of the window
  6973.                                (integer).
  6974.  
  6975.                     RightCol - right column coordinate of the window
  6976.                                (integer).
  6977.  
  6978.                    FrameType - any of the frame types that can be used with
  6979.                                the Box or GSSbox functions (integer).
  6980.  
  6981.                    ScrollBar - a flag to signal the function to draw scroll
  6982.                                bars at the bottom of the display to
  6983.                                indicate the relative position of the cursor
  6984.                                (integer).
  6985.  
  6986.                     BarColor - color attributes for the scroll bars
  6987.                                (integer).
  6988.  
  6989.                        Array - pointer to a null terminated array of
  6990.                                pointers to be displayed.
  6991.  
  6992.                     TagArray - an array that holds which item has been
  6993.                                tagged.  If a null pointer is specified the
  6994.                                function will not permit tagging.  An array
  6995.                                element value of "0" and "1"  indicate the
  6996.                                status for untagged and tagged (char).
  6997.  
  6998.  
  6999.  
  7000.                                      Page -114-
  7001.  
  7002.  
  7003.  
  7004.  
  7005.  
  7006.                           SCL1 Version 2.0 Reference Manual
  7007.  
  7008.  
  7009.                                                                  ListWindow
  7010.  
  7011.                     TagColor - color attributes to be used for displaying a
  7012.                                tagged item (integer).
  7013.  
  7014.                        Title - char pointer to text to be displayed in the
  7015.                                window's top row as a title.
  7016.  
  7017.                   TitleColor - color attributes for the title's display
  7018.                                (integer).
  7019.  
  7020.                     ExitKeys - an array of keys defined to exit the
  7021.                                function (unsigned integer).
  7022.  
  7023.                  StaticWidth - a value of "0" means that the number of
  7024.                                columns will be determined by the maximum
  7025.                                length of any of the items, a value of "1"
  7026.                                sets the width of the columns to the value
  7027.                                defined with ColumnWidth (integer).
  7028.  
  7029.                        Items - structure element (used internally) that
  7030.                                holds the quantity of items in the array
  7031.                                (unsigned integer).
  7032.  
  7033.                  ColumnWidth - width of each column to be displayed window
  7034.                                (unsigned integer).
  7035.  
  7036.                    FirstItem - structure element (used internally) that
  7037.                                holds the position of the first array
  7038.                                element (unsigned integer).
  7039.  
  7040.                     Position - structure element (used internally) that
  7041.                                holds the active position of the display
  7042.                                (unsigned integer).  Note this element
  7043.                                should not be modified by the calling
  7044.                                program but can be read.
  7045.  
  7046.                  WindowLines - structure element (used internally) that
  7047.                                holds the number of lines in the List Window
  7048.                                (integer).
  7049.  
  7050.                   WindowCols - structure element (used internally) that
  7051.                                holds the number of columns in the List
  7052.                                Window (integer).
  7053.  
  7054.                    TotalCols - structure element (used internally) that
  7055.                                holds the maximum number of columns in the
  7056.                                window (integer).
  7057.  
  7058.  
  7059.                                      Page -115-
  7060.  
  7061.  
  7062.  
  7063.  
  7064.  
  7065.                           SCL1 Version 2.0 Reference Manual
  7066.  
  7067.  
  7068.                                                                  ListWindow
  7069.  
  7070.             TotalWindowItems - structure element (used internally) that
  7071.                                holds the number of items (integer).
  7072.  
  7073.                    OldHBlock - structure element (used internally) that
  7074.                                holds the position of the relative position
  7075.                                indicating scroll bar block (integer).
  7076.  
  7077.                    EventInfo - information about the keys that have been
  7078.                                pressed (unsigned integer).
  7079.  
  7080.           Messages:
  7081.  
  7082.           The following messages can be sent to ListWindow:
  7083.  
  7084.                         LW_INIT - initialize the LWData structure to NULL
  7085.                                   and set the following default values:
  7086.  
  7087.                             NColor - set to white characters in a black
  7088.                                      background or the normal color defined
  7089.                                      by calling SetDialogColors.
  7090.  
  7091.                             RColor - set to black characters in a white
  7092.                                      background or the reversed color
  7093.                                      defined by calling SetDialogColors.
  7094.  
  7095.                           LowerRow - one row less than the screen length.
  7096.  
  7097.                           RightCol - one column less than the screen width.
  7098.  
  7099.                          FrameType - set to frame type "1" (single line).
  7100.  
  7101.                          ScrollBar - set to draw scroll bars.
  7102.  
  7103.                           BarColor - set to black characters in a white
  7104.                                      background or the reversed color
  7105.                                      defined by calling SetDialogColors.
  7106.  
  7107.                           TagColor - set to black characters in a white
  7108.                                      background or the reversed color
  7109.                                      defined by calling SetDialogColors.
  7110.  
  7111.                         TitleColor - set to white characters in a black
  7112.                                      background or the normal color defined
  7113.                                      by calling SetDialogColors.
  7114.  
  7115.                          OldHBlock - set to "-1".
  7116.  
  7117.  
  7118.                                      Page -116-
  7119.  
  7120.  
  7121.  
  7122.  
  7123.  
  7124.                           SCL1 Version 2.0 Reference Manual
  7125.  
  7126.  
  7127.                                                                  ListWindow
  7128.  
  7129.                         LW_DRAW - display the list window.
  7130.  
  7131.                        LW_WRITE - draws the window and the list of items to
  7132.                                   the screen.
  7133.  
  7134.                       LW_ACTIVE - browse through the displayed items and
  7135.                                   permit the selection or tagging of them
  7136.                                   using the cursor movement keys as
  7137.                                   follows:
  7138.  
  7139.                          Key                      action
  7140.  
  7141.                        Up Arrow         cursor one item up.
  7142.                        Down Arrow       cursor one item down.
  7143.                        Left Arrow       cursor one item to the left.
  7144.                        Right Arrow      cursor one item to the right.
  7145.                        END              cursor to end of list.
  7146.                        HOME             cursor to beginning of list.
  7147.                        Page Up          cursor one screen up.
  7148.                        Page Down        cursor one screen down.
  7149.  
  7150.                  LW_DRAW_BORDER - draw the List Window's border.
  7151.  
  7152.               LW_POSITION_BEGIN - move cursor to the first item.
  7153.  
  7154.                 LW_POSITION_END - move cursor to the last item.
  7155.  
  7156.                  LW_POSITION_UP - move cursor to the previous item.
  7157.  
  7158.                LW_POSITION_DOWN - move cursor to the next item.
  7159.  
  7160.                 LW_SET_POSITION - move cursor to a specific item.  The item
  7161.                                   number is passed as a parameter.
  7162.  
  7163.                          LW_CLS - clear the list window data area.
  7164.  
  7165.                  LW_CHECK_MOUSE - check if the mouse has been clicked after
  7166.                                   pointing to the area defined by the
  7167.                                   function.
  7168.  
  7169.                        LW_RESET - when this message is sent the position
  7170.                                   variables are reset to the default value. 
  7171.                                   If the exit keys have not been defined
  7172.                                   they are set to the default exit keys.
  7173.  
  7174.  
  7175.  
  7176.  
  7177.                                      Page -117-
  7178.  
  7179.  
  7180.  
  7181.  
  7182.  
  7183.                           SCL1 Version 2.0 Reference Manual
  7184.  
  7185.  
  7186.                                                                  ListWindow
  7187.  
  7188.           The following messages can be returned by ListWindow:
  7189.  
  7190.                   LW_NULL_ARRAY - no item array has been defined.
  7191.  
  7192.                           LW_OK - the requested action has been performed.
  7193.  
  7194.                     LW_EXIT_KEY - a key that has been defined as an exit
  7195.                                   key has been pressed.
  7196.  
  7197.                  LW_MOUSE_EVENT - the mouse has been clicked but it has not
  7198.                                   been pointed to the area defined by the
  7199.                                   function.
  7200.  
  7201.                   LW_BUFFER_END - you have requested to move the cursor
  7202.                                   passed the last item.
  7203.  
  7204.                 LW_BUFFER_BEGIN - you have requested to move the cursor up
  7205.                                   passed the first active item.
  7206.  
  7207.                  LW_ILLEGAL_KEY - a key that has not been defined has been
  7208.                                   pressed.
  7209.  
  7210.             LW_ILLEGAL_POSITION - you have requested to move the cursor to
  7211.                                   an invalid position.
  7212.  
  7213.                 LW_NEW_POSITION - the cursor position has been updated.
  7214.  
  7215.                 LW_MOUSE_SELECT - one of the elements have been selected by
  7216.                                   double clicking the mouse.
  7217.  
  7218.                     LW_MY_MOUSE - response to a LW_CHECK_MOUSE message if
  7219.                                   the mouse has been clicked after pointing
  7220.                                   to the field area defined by the
  7221.                                   function.
  7222.  
  7223.                 LW_NEW_MOUSEPOS - you have moved the cursor by clicking the
  7224.                                   mouse after pointing to an item.
  7225.  
  7226.                   LW_BLOCK_MARK - you have tagged a group of items using
  7227.                                   your mouse.
  7228.  
  7229.  
  7230.  
  7231.  
  7232.  
  7233.  
  7234.  
  7235.  
  7236.                                      Page -118-
  7237.  
  7238.  
  7239.  
  7240.  
  7241.  
  7242.                           SCL1 Version 2.0 Reference Manual
  7243.  
  7244.  
  7245.                                                                  ListWindow
  7246.  
  7247.           Example:
  7248.  
  7249.           #include <scl1.h>
  7250.           #include <scl1clor.h>
  7251.  
  7252.           char *Items[]={   /* Array of items to display */
  7253.               "11111",
  7254.               "22222",
  7255.               "33333",
  7256.               "44444",
  7257.               "55555",
  7258.               "66666",
  7259.               "77777",
  7260.               "88888",
  7261.               "99999",
  7262.               "00000",
  7263.               0,            /* terminated with a "0" */
  7264.               };
  7265.  
  7266.           char TagA[10];
  7267.  
  7268.           int Color1=BLACK_WHITE;
  7269.           int Color2=WHITE_BLACK;
  7270.  
  7271.           main()
  7272.           {
  7273.           int EMess;
  7274.           LWData lw;        /* set lw as type LWData */
  7275.  
  7276.           ListWindow(LW_INIT,&lw);
  7277.           lw.UpperRow=5;             /* Set window size */
  7278.           lw.LowerRow=10;
  7279.           lw.LeftCol=30;
  7280.           lw.RightCol=40;
  7281.           lw.RColor=Color2;
  7282.           lw.TagArray=TagA;
  7283.           lw.Array=Items;
  7284.           ListWindow(LW_DRAW,&lw);
  7285.           do
  7286.               {
  7287.               EMess=ListWindow(LW_ACTIVE,&lw);
  7288.               }while(EMess != LW_EXIT_KEY);
  7289.           }
  7290.  
  7291.  
  7292.  
  7293.  
  7294.  
  7295.                                      Page -119-
  7296.  
  7297.  
  7298.  
  7299.  
  7300.  
  7301.                           SCL1 Version 2.0 Reference Manual
  7302.  
  7303.  
  7304.                                                                     MakeDir
  7305.  
  7306.           Function:    MakeDir
  7307.  
  7308.           Purpose:     Creates a new directory.
  7309.  
  7310.           Declaration: int MakeDir(char *Path);
  7311.  
  7312.           Returns:     The return value is "0" if no error occurs or the
  7313.                        DOS error code if an error occurs.  (See Appendix
  7314.                        "A", FILE FUNCTIONS, for more information).
  7315.  
  7316.           Parameters:
  7317.  
  7318.                   Path - char pointer to a string holding the new directory
  7319.                          name.
  7320.  
  7321.           Example:
  7322.  
  7323.           #include <scl1.h>
  7324.  
  7325.           main()
  7326.              {
  7327.              MakeDir("SCL1");
  7328.              }
  7329.  
  7330.  
  7331.  
  7332.  
  7333.  
  7334.  
  7335.  
  7336.  
  7337.  
  7338.  
  7339.  
  7340.  
  7341.  
  7342.  
  7343.  
  7344.  
  7345.  
  7346.  
  7347.  
  7348.  
  7349.  
  7350.  
  7351.  
  7352.  
  7353.  
  7354.                                      Page -120-
  7355.  
  7356.  
  7357.  
  7358.  
  7359.  
  7360.                           SCL1 Version 2.0 Reference Manual
  7361.  
  7362.  
  7363.                                                                        Menu
  7364.  
  7365.           Function:    Menu
  7366.  
  7367.           Purpose:     Displays a scrolling or moving bar type menu.  A
  7368.                        selection is made by either pressing the highlighted
  7369.                        menu option letter or by scrolling the highlighted
  7370.                        bar using the arrow keys and then pressing the ENTER
  7371.                        (RETURN) key.  This function permits full control of
  7372.                        the menu's appearance, size and position.  The menu
  7373.                        items can be placed anywhere in the screen and in
  7374.                        any desired order, you are not limited to placing
  7375.                        all the menu options in successive lines.
  7376.  
  7377.           Declaration: int Menu(int NColor, int RColor, int HColor,
  7378.                            int NumOpt, struct MenuOpt *mo);
  7379.  
  7380.  
  7381.           Returns:     The highlighted selection number (>0) or -1 if ESC
  7382.                        is pressed.
  7383.  
  7384.           Parameters:
  7385.  
  7386.           The menu information must be entered as an array of structures as
  7387.           follows; with one array element for each menu option:
  7388.  
  7389.              struct MenuOpt{
  7390.                 int Row,Col;
  7391.                 char *String;
  7392.                 char Letter;
  7393.                 };
  7394.  
  7395.           where:
  7396.  
  7397.                    Row - row position for the menu item (integer).
  7398.  
  7399.                    Col - column position for the menu item (integer).
  7400.  
  7401.                 String - pointer to the menu item text.
  7402.  
  7403.                 Letter - letter to be highlighted for fast keyboard
  7404.                          selection of the menu item (char).
  7405.  
  7406.  
  7407.  
  7408.  
  7409.  
  7410.  
  7411.  
  7412.  
  7413.                                      Page -121-
  7414.  
  7415.  
  7416.  
  7417.  
  7418.  
  7419.                           SCL1 Version 2.0 Reference Manual
  7420.  
  7421.  
  7422.                                                                        Menu
  7423.  
  7424.           The parameters passed to the function are:
  7425.  
  7426.                 NColor - color attribute for the menu background and
  7427.                          foreground (integer).
  7428.  
  7429.                 RColor - color attribute for the highlighted item menu bar
  7430.                          (integer).
  7431.  
  7432.                 HColor - color attribute for the highlighted quick
  7433.                          selection menu item letter (integer).
  7434.  
  7435.                 NumOpt - number of menu options (integer).
  7436.  
  7437.                MenuOpt - pointer to the menu structure previously defined.
  7438.  
  7439.           Example:
  7440.  
  7441.           #include <scl1.h>
  7442.           #include <scl1clor.h>
  7443.  
  7444.           struct MenuOpt Mainmenu[7]={  /*Array of structures with seven
  7445.                                           elements */
  7446.               5,24,"Screen Related Functions    ",'S', /* First option   */
  7447.               7,24,"Keyboard Handling Functions ",'K', /* Second option  */
  7448.               9,24,"Mouse Handling Functions    ",'M', /* Third option   */
  7449.              11,24,"Program Flow Functions      ",'P', /* Fourth option  */
  7450.              13,24,"File Handling Functions     ",'F', /* Fifth option   */
  7451.              15,24,"Background and Miscellaneous",'B', /* Sixth option   */
  7452.              17,24,"Exit Demo                   ",'E', /* Seventh option */
  7453.                 };
  7454.  
  7455.           int Color1=BLACK_WHITE;
  7456.           int Color2=WHITE_BLACK;
  7457.           int Color3=BLACK_WHITE+HIGHLIGHT;
  7458.  
  7459.           main()
  7460.              {
  7461.              int Selection;
  7462.              Box(Color1,5,1,5,18,25); /* Box for menu */
  7463.              WriteScreen(Color1,2,11,"FUNCTIONS"); /* Menu title */
  7464.              Selection=Menu(Color1,Color2,Color3,7,Mainmenu);
  7465.              }
  7466.  
  7467.  
  7468.  
  7469.  
  7470.  
  7471.  
  7472.                                      Page -122-
  7473.  
  7474.  
  7475.  
  7476.  
  7477.  
  7478.                           SCL1 Version 2.0 Reference Manual
  7479.  
  7480.  
  7481.                                                                     MenuSys
  7482.  
  7483.           Function:    MenuSys    (OBSOLETE, use the MenuSystem function,
  7484.                                   this function will eventually be removed
  7485.                                   from future versions of SCL1.)
  7486.  
  7487.           Purpose:     Displays a pull-down menu system in the top of the
  7488.                        screen.  The number of pull-down menus is defined by
  7489.                        the programmer.  All the pull-down menus perform and
  7490.                        are defined as for the Menu function.  The function
  7491.                        requires the programmer to define various structures
  7492.                        and data blocks, although this approach seems to be
  7493.                        complex it gives full control of the size, position
  7494.                        and appearance of the menu.  Supports mouse control.
  7495.  
  7496.           Declaration: int MenuSys(int NColor,int RColor,int HColor,
  7497.                                    int MenuNumber,struct BarMenu *bm,
  7498.                                    struct MenuSysData *msd);
  7499.  
  7500.           Returns:     Return value is the highlighted selection number,
  7501.                        "-1" if the ESC key is pressed or "0" if no
  7502.                        selection is made.  The function returns two digits,
  7503.                        the first corresponding to the pull-down menu number
  7504.                        and the second corresponding to the option selected
  7505.                        in that menu.  The calling program must create a
  7506.                        loop for calling the function when required.
  7507.  
  7508.           Parameters:
  7509.  
  7510.           The menu information must be given as an array of structures as
  7511.           follows:
  7512.  
  7513.              1. Define the Top Row menu information as follows, one element
  7514.                 for each of the main options:
  7515.  
  7516.                 struct BarMenu{
  7517.                    int StartCol,EndCol;
  7518.                    char String[20];
  7519.                    };
  7520.  
  7521.              where;
  7522.  
  7523.               StartCol - column position of the first character of the
  7524.                          option's prompt (integer).
  7525.  
  7526.                 EndCol - column position of the last character of the
  7527.                          option's prompt (integer).
  7528.  
  7529.  
  7530.  
  7531.                                      Page -123-
  7532.  
  7533.  
  7534.  
  7535.  
  7536.  
  7537.                           SCL1 Version 2.0 Reference Manual
  7538.  
  7539.  
  7540.                                                                     MenuSys
  7541.  
  7542.                 String - pointer to a string value containing the option's
  7543.                          prompt, equal to or shorter than 19 characters
  7544.                          (char).
  7545.  
  7546.              Note: The StartCol and EndCol information is used by MenuSys
  7547.                    to determine the mouse range for that option and to
  7548.                    highlight it when selected, for proper operation make
  7549.                    sure that options do not overlap.
  7550.  
  7551.              2. Define one MenuOpt structure for each of the pull-down
  7552.                 menus.  This structure is identical to that used by the
  7553.                 Menu and MouseMenu functions:
  7554.  
  7555.                 struct MenuOpt{
  7556.                    int Row,Col;
  7557.                    char *String;
  7558.                    char Letter;
  7559.                    };
  7560.  
  7561.              where:
  7562.  
  7563.                MenuOpt - name or reference to the menu.
  7564.  
  7565.                    Row - row position for the menu item (integer).
  7566.  
  7567.                    Col - column position for the menu item (integer).
  7568.  
  7569.                 String - pointer to the menu item text (char).
  7570.  
  7571.                 Letter - letter to be highlighted for fast keyboard
  7572.                          selection of the menu item (char).
  7573.  
  7574.           3. Define a PopMenuData structure for each of the pull-down menus
  7575.              as follows:
  7576.  
  7577.                 struct PopMenuData{
  7578.                    int L1,C1,L2,C2;
  7579.                    int NumberOption;
  7580.                    char *WinBuffer;
  7581.                    struct MenuOpt *Menust;
  7582.                    };
  7583.  
  7584.              where;
  7585.  
  7586.                        L1 - upper left row coordinate of the box used to
  7587.                             enclose the pull-down menu (integer).
  7588.  
  7589.  
  7590.                                      Page -124-
  7591.  
  7592.  
  7593.  
  7594.  
  7595.  
  7596.                           SCL1 Version 2.0 Reference Manual
  7597.  
  7598.  
  7599.                                                                     MenuSys
  7600.  
  7601.                        C1 - upper left column coordinate of the box
  7602.                             (integer).
  7603.  
  7604.                        L2 - lower right row coordinate of the box
  7605.                             (integer).
  7606.  
  7607.                        C2 - lower right column coordinate of the box
  7608.                             (integer).
  7609.  
  7610.             NumberOptions - number of options of the pull-down menu
  7611.                             (integer).
  7612.  
  7613.                 WinBuffer - buffer to store the screen area used when
  7614.                             popping out the pull-down menu (char).
  7615.  
  7616.                   MenuOpt - pointer to the MenuOption structure
  7617.                             corresponding to that pull-down menu.
  7618.  
  7619.           4. Define a MenuSysData structure with one element for each of
  7620.              the pull-down menus as follows:
  7621.  
  7622.                 struct MenuSysData{
  7623.                    unsigned int Key;
  7624.                    struct PopMenuData *PMenu;
  7625.                    };
  7626.  
  7627.              where;
  7628.  
  7629.                       Key - key to activate that pull-down menu. (required
  7630.                             for keyboard control of the menu system)
  7631.                             (unsigned integer).
  7632.  
  7633.               PopMenuData - pointer to the PopMenuData structure.
  7634.  
  7635.           The MenuSys function is called with the following parameters:
  7636.  
  7637.                 NColor - color attribute of the menus (integer).
  7638.  
  7639.                 RColor - reverse color attributes (integer).
  7640.  
  7641.                 HColor - highlight color attributes (integer).
  7642.  
  7643.             MenuNumber - number of pull-down menus (integer).
  7644.  
  7645.                BarMenu - pointer to the BarMenu structure.
  7646.  
  7647.            MenuSysData - pointer to the MenuSysData structure.
  7648.  
  7649.                                      Page -125-
  7650.  
  7651.  
  7652.  
  7653.  
  7654.  
  7655.                           SCL1 Version 2.0 Reference Manual
  7656.  
  7657.  
  7658.                                                                     MenuSys
  7659.  
  7660.           Example:
  7661.  
  7662.           #include <scl1.h>
  7663.           #include <scl1clor.h>
  7664.           #include <scl1keys.h>
  7665.  
  7666.           int Color1=BLACK_WHITE;
  7667.           int Color2=WHITE_BLACK;
  7668.           int Color3=BLACK_WHITE+HIGHLIGHT;
  7669.  
  7670.           /* Bar Menu Structure */
  7671.           struct BarMenu bd[]={
  7672.              3,9,"F1 File",
  7673.              17,23,"F2 Edit",
  7674.              };
  7675.  
  7676.           /* First pop-menu structure */
  7677.           struct MenuOpt Men1[]={
  7678.              2,5,"New    ",'N',
  7679.              3,5,"Open   ",'O',
  7680.              4,5,"Close  ",'C',
  7681.              5,5,"Save   ",'S',
  7682.              6,5,"Exit   ",'E',
  7683.              };
  7684.  
  7685.           /* Second pop-menu structure */
  7686.           struct MenuOpt Men2[]={
  7687.              2,19,"Copy   ",'C',
  7688.              3,19,"Delete ",'D',
  7689.              4,19,"Insert ",'I',
  7690.              5,19,"Cancel ",'a'};
  7691.  
  7692.           struct PopMenuData bd1[]={
  7693.              1,3,7,13,
  7694.              5,
  7695.              WinBuf1,
  7696.              Men1,
  7697.  
  7698.              1,17,6,27,
  7699.              4,
  7700.              WinBuf1,
  7701.              Men2,
  7702.              };
  7703.  
  7704.  
  7705.  
  7706.  
  7707.  
  7708.                                      Page -126-
  7709.  
  7710.  
  7711.  
  7712.  
  7713.  
  7714.                           SCL1 Version 2.0 Reference Manual
  7715.  
  7716.  
  7717.                                                                     MenuSys
  7718.  
  7719.           struct MenuSysData msd1[]={
  7720.              F1,
  7721.              &bd1[0],
  7722.  
  7723.              F2,
  7724.              &bd1[1],
  7725.              };
  7726.  
  7727.           main()
  7728.              {
  7729.              int Selection;
  7730.              /* Draws the top row prompts*/
  7731.              DrawBarMenu(Color1,Color2,2,0,bd);
  7732.  
  7733.              /* Loop until the exit option is selected */
  7734.              do
  7735.                 {
  7736.                 Selection=MenuSys(Color1,Color2,Color3,2,bd,msd1);
  7737.  
  7738.                 /* Discard any invalid key pressed */
  7739.                 if(!((KeyReady()>F1)&&(KeyReady()<F4)))
  7740.                      ClearKeyBuf();
  7741.                 }while((Selection==0)||(Selection!=15));
  7742.              }
  7743.           In the above example the exit option is the fifth of the first
  7744.           pull-down menu.
  7745.  
  7746.  
  7747.  
  7748.  
  7749.  
  7750.  
  7751.  
  7752.  
  7753.  
  7754.  
  7755.  
  7756.  
  7757.  
  7758.  
  7759.  
  7760.  
  7761.  
  7762.  
  7763.  
  7764.  
  7765.  
  7766.  
  7767.                                      Page -127-
  7768.  
  7769.  
  7770.  
  7771.  
  7772.  
  7773.                           SCL1 Version 2.0 Reference Manual
  7774.  
  7775.  
  7776.                                                                  MenuSystem
  7777.  
  7778.           Function:    MenuSystem
  7779.  
  7780.           Purpose:     Displays a pull-down menu system in the top of the
  7781.                        screen. The function requires the programmer to
  7782.                        define various structures and data blocks, although
  7783.                        this approach seems to be complex it gives full
  7784.                        control of the size, position and appearance of the
  7785.                        menu.  Supports mouse control.  This is a dialog
  7786.                        type function.
  7787.  
  7788.           Declaration: int MenuSystem(int Message,MSData *msd,...);
  7789.  
  7790.           Returns:     This is a dialog type function. See Appendix "E" for
  7791.                        a description of the general operation of these
  7792.                        functions. The return value is a message described
  7793.                        in the Messages section.
  7794.  
  7795.           Parameters:
  7796.  
  7797.           The menu information must be given in an array of structures as
  7798.           follows; one element for each pull-down menu:
  7799.  
  7800.           1. The top row menu information is defined as an array of
  7801.              structures type MSBar as follows, one element for each of the
  7802.              main options:
  7803.  
  7804.              typedef struct{
  7805.                 int StartCol;
  7806.                 int EndCol;
  7807.                 unsigned int Key;
  7808.                 char *String;
  7809.                 }MSBar;
  7810.  
  7811.           where;
  7812.  
  7813.               StartCol - column position of the first character of the
  7814.                          option's prompt (integer).
  7815.  
  7816.                 EndCol - column position of the last character of the
  7817.                          option's prompt (integer).
  7818.  
  7819.                    Key - unsigned integer structure member that indicates
  7820.                          which key will be used to call the pull-down menu.
  7821.                          (This is important when using keyboard input).
  7822.  
  7823.  
  7824.  
  7825.  
  7826.                                      Page -128-
  7827.  
  7828.  
  7829.  
  7830.  
  7831.  
  7832.                           SCL1 Version 2.0 Reference Manual
  7833.  
  7834.  
  7835.                                                                  MenuSystem
  7836.  
  7837.                 String - pointer to a string value containing the option's
  7838.                          prompt.
  7839.  
  7840.              Note: The StartCol and EndCol information is used by
  7841.                    MenuSystem to determine the mouse range for that option
  7842.                    and to highlight it when selected.  For proper operation
  7843.                    make sure that options do not overlap.
  7844.  
  7845.           2. Each pull-down menu is defined as an array of structures type
  7846.              MSOptions.  The structure is similar to that used for the Menu
  7847.              function.
  7848.  
  7849.              typedef struct{
  7850.                 int Row;
  7851.                 int Col;
  7852.                 char *String;
  7853.                 char Letter;
  7854.                 }MSOptions;
  7855.  
  7856.              where:
  7857.  
  7858.                    Row - row position for the menu item (integer).
  7859.  
  7860.                    Col - column position for the menu item (integer).
  7861.  
  7862.                 String - pointer to the menu item text.
  7863.  
  7864.                 Letter - letter to be highlighted for fast keyboard
  7865.                          selection of the menu item (char).
  7866.  
  7867.           3. The pull down menu box information is defined in a structure
  7868.              type MSWindows as an array of structures for the menusystem,
  7869.              one element for each pull-down menu as follows:
  7870.  
  7871.              typedef struct{
  7872.                 int UpperRow;
  7873.                 int LeftCol;
  7874.                 int LowerRow;
  7875.                 int RightCol;
  7876.                 int Number;
  7877.                 char *WinBuffer;
  7878.                 MSOptions *mso;
  7879.                 }MSWindow;
  7880.  
  7881.  
  7882.  
  7883.  
  7884.  
  7885.                                      Page -129-
  7886.  
  7887.  
  7888.  
  7889.  
  7890.  
  7891.                           SCL1 Version 2.0 Reference Manual
  7892.  
  7893.  
  7894.                                                                  MenuSystem
  7895.  
  7896.           where;
  7897.  
  7898.                  UpperRow - upper row coordinate of the box used to enclose
  7899.                             the pulldown menu (integer).
  7900.  
  7901.                   LeftCol - left column coordinate of the box (integer).
  7902.  
  7903.                  LowerRow - lower row coordinate of the box (integer).
  7904.  
  7905.                  RightCol - right column coordinate of the box (integer).
  7906.  
  7907.                    Number - number of options of the pull-down menu
  7908.                             (integer).
  7909.  
  7910.                 WinBuffer - buffer to store the screen area used when
  7911.                             popping out the pull-down menu.
  7912.  
  7913.                 MSOptions - pointer to the MSOptions structure
  7914.                             corresponding to that pull-down menu.
  7915.  
  7916.           4. The remaining information is defined in a structure type
  7917.              MSData as follows:
  7918.  
  7919.              typedef struct{
  7920.                 int BarNColor;
  7921.                 int BarRColor;
  7922.                 int MenuNColor;
  7923.                 int MenuRColor;
  7924.                 int MenuHColor;
  7925.                 MSBar *msb;
  7926.                 MSWindow *msw;
  7927.                 int Number;
  7928.                 int Menu;
  7929.                 int Option;
  7930.                 unsigned int EventInfo;
  7931.                 }MSData;
  7932.  
  7933.           where;
  7934.  
  7935.              BarNColor - normal color attributes for top row or bar menu
  7936.                          (integer).
  7937.  
  7938.              BarRColor - reversed color attributes for top row or bar menu
  7939.                          (integer).
  7940.  
  7941.  
  7942.  
  7943.  
  7944.                                      Page -130-
  7945.  
  7946.  
  7947.  
  7948.  
  7949.  
  7950.                           SCL1 Version 2.0 Reference Manual
  7951.  
  7952.  
  7953.                                                                  MenuSystem
  7954.  
  7955.             MenuNColor - normal color attributes for the pull-down menus
  7956.                          (integer).
  7957.  
  7958.             MenuRColor - Reversed color attributes for the pull-down menus
  7959.                          (integer).
  7960.  
  7961.             MenuHColor - highlight color attributes for hot-keys in pull
  7962.                          down menus (integer).
  7963.  
  7964.                   MBar - pointer to the corresponding MSBar structure.
  7965.  
  7966.               MSWindow - pointer to the corresponding MSWindow structure.
  7967.  
  7968.                 Number - number of pull-down menus in the system (integer).
  7969.  
  7970.                   Menu - structure member holding the active pull-down menu
  7971.                          number (integer).
  7972.  
  7973.                 Option - structure member holding the active option of the
  7974.                          selected pull-down menu (integer).
  7975.  
  7976.              EventInfo - structure member holding the event information for
  7977.                          the menusystem. (unsigned integer).
  7978.  
  7979.            MenuSysData - pointer to the MenuSysData structure.
  7980.  
  7981.           Messages:
  7982.  
  7983.           The following messages can be sent to Menusystem:
  7984.  
  7985.                         MS_INIT - initialize the MSData structure to NULL
  7986.                                   and set the following values as follows:
  7987.  
  7988.                                  BarNColor - set to black characters in a
  7989.                                              white background or the
  7990.                                              reversed color defined by
  7991.                                              calling SetDialogColors.
  7992.  
  7993.                                  BarRColor - set to white characters in a
  7994.                                              black background or the normal
  7995.                                              color defined by calling
  7996.                                              SetDialogColors.
  7997.  
  7998.                                 MenuNColor - set to white characters in a
  7999.                                              black background or the normal
  8000.                                              color defined by calling
  8001.                                              SetDialogColors.
  8002.  
  8003.                                      Page -131-
  8004.  
  8005.  
  8006.  
  8007.  
  8008.  
  8009.                           SCL1 Version 2.0 Reference Manual
  8010.  
  8011.  
  8012.                                                                  MenuSystem
  8013.  
  8014.                                 MenuRColor - set to black characters in a
  8015.                                              white background or the
  8016.                                              reversed color defined by
  8017.                                              calling SetDialogColors.
  8018.  
  8019.                                 MenuHColor - set to highlighted white
  8020.                                              characters in a black
  8021.                                              background or the normal color
  8022.                                              defined by calling
  8023.                                              SetDialogColors.
  8024.  
  8025.                         MS_DRAW - draw the bar menu.
  8026.  
  8027.                        MS_CHECK - checks if any key or mouse event related
  8028.                                   to the MenuSystem has been activated in
  8029.                                   which case it will retain control and
  8030.                                   respond to the following keys:
  8031.  
  8032.                          Key                      action
  8033.  
  8034.                        Up Arrow         cursor to previous option.
  8035.                        Down Arrow       cursor to next option.
  8036.                        Left Arrow       select previous pull-down menu.
  8037.                        Right Arrow      select next pull-down menu.
  8038.  
  8039.                          MS_KEY - the parameter passed with this message
  8040.                                   (Scan+Ascii code of the key) is a control
  8041.                                   key value that performs as if the control
  8042.                                   key has been pressed.
  8043.  
  8044.                    MS_SHADOW_ON - turn on a shadow effect for pull-down
  8045.                                   menus.  Make sure to set enough space for
  8046.                                   the shadow characters in the MSWindows
  8047.                                   structure.
  8048.  
  8049.                   MS_SHADOW_OFF - turn off shadow effect on pull-down
  8050.                                   menus.
  8051.  
  8052.                      MS_LINE_ON - draw horizontal lines on empty spaces
  8053.                                   inside a menu box.
  8054.  
  8055.                     MS_LINE_OFF - do not draw horizontal lines on empty
  8056.                                   spaces in menu box (default).
  8057.  
  8058.               MS_SET_FRAME_TYPE - sets the frame type for pull down menus
  8059.                                   to the type specified with an additional
  8060.                                   parameter (default is single line).
  8061.  
  8062.                                      Page -132-
  8063.  
  8064.  
  8065.  
  8066.  
  8067.  
  8068.                           SCL1 Version 2.0 Reference Manual
  8069.  
  8070.  
  8071.                                                                  MenuSystem
  8072.  
  8073.                  MS_SET_BAR_ROW - sets the row position where to display
  8074.                                   the bar menu to the value specified with
  8075.                                   an additional parameter (default is "0").
  8076.  
  8077.                MS_SET_BAR_START - sets the column position where the bar
  8078.                                   menu starts to the value specified with
  8079.                                   an additional parameter (default is "0").
  8080.  
  8081.                  MS_SET_BAR_END - sets the column position where the bar
  8082.                                   menu ends to the value specified with an
  8083.                                   additional parameter (default is the
  8084.                                   maximum screen width).
  8085.  
  8086.                       MS_ALT_ON - set ALT key to bring down pull-down
  8087.                                   menus.
  8088.  
  8089.                      MS_ALT_OFF - disable the ALT key to bring pull-down
  8090.                                   menus.
  8091.  
  8092.              MS_SET_FRAME_COLOR - set the pull-down menu box' frame color,
  8093.                                   if this message is not sent it is set to
  8094.                                   normal color.
  8095.  
  8096.            MS_RESET_FRAME_COLOR - reset the pull-down menu box's frame to
  8097.                                   normal color.
  8098.  
  8099.           The following messages can be returned by Menusystem:
  8100.  
  8101.                    MS_NO_SELECT - no selection has been made.
  8102.  
  8103.                           MS_OK - action requested has been successfully
  8104.                                   performed.
  8105.  
  8106.                       MS_SELECT - a selection has been made. This means
  8107.                                   that the structure element containing the
  8108.                                   selection information must be checked to
  8109.                                   determine what has been the selection.
  8110.  
  8111.                       MS_CANCEL - the mouse has been clicked after pointing
  8112.                                   outside the window area or the "ESC" key
  8113.                                   has been pressed.
  8114.  
  8115.  
  8116.  
  8117.  
  8118.  
  8119.  
  8120.  
  8121.                                      Page -133-
  8122.  
  8123.  
  8124.  
  8125.  
  8126.  
  8127.                           SCL1 Version 2.0 Reference Manual
  8128.  
  8129.  
  8130.                                                                  MenuSystem
  8131.  
  8132.           Example:
  8133.  
  8134.  
  8135.           #include <scl1.h>
  8136.           #include <scl1keys.h>
  8137.           #include <scl1clor.h>
  8138.  
  8139.           MSBar msb[]={
  8140.  
  8141.           /* Menu-bar data:
  8142.              Start and end column of each option
  8143.              Menu's key SCAN-ASCII code
  8144.              String */
  8145.  
  8146.              1,6,0x2100," File ",
  8147.              7,12,0x1200," Edit ",
  8148.              };
  8149.  
  8150.           /* first pull-down menu
  8151.              row, column position
  8152.              string
  8153.              hot-key */
  8154.  
  8155.           MSOptions mso0[]={
  8156.              2,1," Load ",'L',
  8157.              3,1," Save ",'S',
  8158.              4,1," Quit ",'Q',
  8159.              };
  8160.  
  8161.           /* second pull-down menu */
  8162.  
  8163.           MSOptions mso1[]={
  8164.              2,7," Mark  ",'M',
  8165.              3,7," Cut   ",'C',
  8166.              4,7," Copy  ",'y',
  8167.              5,7," Paste ",'P',
  8168.              };
  8169.  
  8170.           /* buffer for storing pull down menu screen area */
  8171.  
  8172.           char WindowBuf[140];
  8173.  
  8174.  
  8175.  
  8176.  
  8177.  
  8178.  
  8179.  
  8180.                                      Page -134-
  8181.  
  8182.  
  8183.  
  8184.  
  8185.  
  8186.                           SCL1 Version 2.0 Reference Manual
  8187.  
  8188.  
  8189.                                                                  MenuSystem
  8190.  
  8191.           /* Pull-down menu box & window information
  8192.  
  8193.              top left corner and bottom right corner coordinates
  8194.              number of options
  8195.              buffer for saving screen area
  8196.              MSOptions structure  */
  8197.  
  8198.           MSWindow msw[]={
  8199.              1,0,5,7,3,WindowBuf,mso0,
  8200.              1,6,6,14,4,WindowBuf,mso1,
  8201.              };
  8202.  
  8203.           /* This structure links all previous structures */
  8204.  
  8205.           MSData msd=
  8206.              {
  8207.  
  8208.              /* bar-menu colors */
  8209.              BLACK_WHITE,WHITE_BLACK+HIGHLIGHT,
  8210.  
  8211.              /* pull-down menu colors */
  8212.              WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+HIGHLIGHT,
  8213.  
  8214.              /* MSBar, MSWindow structures, number of menus and internal
  8215.                 variables */
  8216.  
  8217.              msb,msw,2,0,0,0};
  8218.  
  8219.           main()
  8220.              {
  8221.              int Mess;
  8222.  
  8223.              InitMouse(IM_SHOW); /* initialize mouse */
  8224.  
  8225.              /* Draw shadows */
  8226.              MenuSystem(MS_SHADOW_ON,(MSData *)0);
  8227.  
  8228.              /* MenuSystem will be ALT sensitive */
  8229.              MenuSystem(MS_ALT_ON,(MSData *)0);
  8230.  
  8231.              /* draw */
  8232.              MenuSystem(MS_DRAW,&msd);
  8233.  
  8234.  
  8235.  
  8236.  
  8237.  
  8238.  
  8239.                                      Page -135-
  8240.  
  8241.  
  8242.  
  8243.  
  8244.  
  8245.                           SCL1 Version 2.0 Reference Manual
  8246.  
  8247.  
  8248.                                                                  MenuSystem
  8249.  
  8250.              do
  8251.                 {
  8252.                 /* a key pressed? */
  8253.  
  8254.                 if(Mess=KeyReady())
  8255.                    {
  8256.  
  8257.                    /* send key to MenuSystem */
  8258.                    Mess=MenuSystem(MS_KEY,&msd,Mess);
  8259.  
  8260.                    /* If we still have a key it means it was not a
  8261.                       MenuSystem key, discard key. If your program needs to
  8262.                       service the keyboard you should do it here. */
  8263.  
  8264.                    if(KeyReady())
  8265.                        GetKey();
  8266.                    }
  8267.                 else
  8268.  
  8269.                    /* Let MenuSystem check if the mouse has been clicked
  8270.                       or a selection has been made */
  8271.                    Mess=MenuSystem(MS_CHECK,&msd);
  8272.  
  8273.                    if(Mess==MS_SELECT)
  8274.                        {
  8275.  
  8276.                        /* a selection was made, msd.Menu=selected menu */
  8277.  
  8278.                        switch(msd.Menu)
  8279.                          {
  8280.                          case 1:
  8281.  
  8282.                          /* first menu, msd.Option=selected option */
  8283.  
  8284.                             switch(msd.Option)
  8285.                                {
  8286.                                case 1:
  8287.                                   /* first option */
  8288.                                   MessageOn(BLACK_WHITE,"Load");
  8289.                                   WaitTime(100);
  8290.                                   MessageOff();break;
  8291.                                case 2:
  8292.                                   /* second option */
  8293.                                   MessageOn(BLACK_WHITE,"Save");
  8294.                                   WaitTime(100);
  8295.                                   MessageOff();break;
  8296.  
  8297.  
  8298.                                      Page -136-
  8299.  
  8300.  
  8301.  
  8302.  
  8303.  
  8304.                           SCL1 Version 2.0 Reference Manual
  8305.  
  8306.  
  8307.                                                                  MenuSystem
  8308.  
  8309.                                case 3:
  8310.                                   /* third option */
  8311.                                   MessageOn(BLACK_WHITE,"Quit");
  8312.                                   WaitTime(100);
  8313.                                   MessageOff();
  8314.                                   break;
  8315.                                   }
  8316.                          break;
  8317.  
  8318.                        case 2:
  8319.  
  8320.                             /* second menu */
  8321.                             switch(msd.Option)
  8322.                                {
  8323.                                case 1:
  8324.                                   /* first option */
  8325.                                   MessageOn(BLACK_WHITE,"Mark");
  8326.                                   WaitTime(100);
  8327.                                   MessageOff();
  8328.                                   break;
  8329.                                case 2:
  8330.                                   /* second option */
  8331.                                   MessageOn(BLACK_WHITE,"Cut");
  8332.                                   WaitTime(100);
  8333.                                   MessageOff();
  8334.                                   break;
  8335.                                case 3:
  8336.                                   /* third option */
  8337.                                   MessageOn(BLACK_WHITE,"Copy");
  8338.                                   WaitTime(100);
  8339.                                   MessageOff();
  8340.                                   break;
  8341.                                case 4:
  8342.                                   /* fourth option */
  8343.                                   MessageOn(BLACK_WHITE,"Paste");
  8344.                                   WaitTime(100);
  8345.                                   MessageOff();
  8346.                                   break;
  8347.                                }
  8348.                             break;
  8349.                          }
  8350.                    }
  8351.                 }while(msd.Menu != 1 || msd.Option != 3);
  8352.              }
  8353.  
  8354.  
  8355.  
  8356.  
  8357.                                      Page -137-
  8358.  
  8359.  
  8360.  
  8361.  
  8362.  
  8363.                           SCL1 Version 2.0 Reference Manual
  8364.  
  8365.  
  8366.                                                                  MessageOff
  8367.  
  8368.           Function:    MessageOff
  8369.  
  8370.           Purpose:     Removes the message box displayed by MessageOn and
  8371.                        restores the screen's previous contents.
  8372.  
  8373.           Declaration: void MessageOff(void);
  8374.  
  8375.           Returns:     Nothing
  8376.  
  8377.           Parameters:  None
  8378.  
  8379.           Example:
  8380.  
  8381.           #include <scl1.h>
  8382.           #include <scl1clor.h>
  8383.  
  8384.           main()
  8385.              {
  8386.              int i;
  8387.              char buffer[8];
  8388.              memset(buffer,0,sizeof(buffer));
  8389.  
  8390.              /* display message */
  8391.              MessageOn(WHITE_BLACK,"Counting to 30,000...");
  8392.  
  8393.              /* loop */
  8394.              for(i=0;i < 30000; i++)
  8395.  
  8396.                 /* write inside MessageOn screen area */
  8397.                 WriteScreen(WHITE_BLACK,11,38,Bin2Ascii((long)i,buffer));
  8398.  
  8399.              /* restore screen */
  8400.              MessageOff();
  8401.           }
  8402.  
  8403.           See also MessageOn, MessageShadowOff and MessageShadowOn.
  8404.  
  8405.  
  8406.  
  8407.  
  8408.  
  8409.  
  8410.  
  8411.  
  8412.  
  8413.  
  8414.  
  8415.  
  8416.                                      Page -138-
  8417.  
  8418.  
  8419.  
  8420.  
  8421.  
  8422.                           SCL1 Version 2.0 Reference Manual
  8423.  
  8424.  
  8425.                                                                   MessageOn
  8426.  
  8427.           Function:    MessageOn
  8428.  
  8429.           Purpose:     Displays a message inside a box in the center of the
  8430.                        screen.  The screen area is saved and is restored
  8431.                        when MessageOff is called.
  8432.  
  8433.           Declaration: void MessageOn(int Color, char *String);
  8434.  
  8435.           Returns:     Nothing
  8436.  
  8437.           Parameters:
  8438.  
  8439.                  Color - Box/message color (integer).
  8440.  
  8441.                 String - pointer to string.
  8442.  
  8443.           Note:    Messages are written inside a box.  They can have up to
  8444.                    5 lines with up to 40 characters each.  Use control
  8445.                    character '\n' to indicate new line.  The box will stay
  8446.                    on the screen until MessageOff is called.  Each line
  8447.                    will be centered in the window.  Lines will also be
  8448.                    centered vertically.
  8449.  
  8450.           Example:
  8451.  
  8452.           #include <scl1.h>
  8453.           #include <scl1clor.h>
  8454.  
  8455.           main()
  8456.              {
  8457.              int i;
  8458.              char buffer[8];
  8459.              memset(buffer,0,sizeof(buffer));
  8460.  
  8461.              /* display message */
  8462.              MessageOn(WHITE_BLACK,"Counting to 30,000...");
  8463.  
  8464.              /* loop */
  8465.              for(i=0;i < 30000; i++)
  8466.  
  8467.                 /* write inside MessageOn screen area */
  8468.                 WriteScreen(WHITE_BLACK,11,38,Bin2Ascii((long)i,buffer));
  8469.  
  8470.              /* restore screen */
  8471.              MessageOff();
  8472.           }
  8473.           See also MessageOff, MessageShadowOff and MessageShadowOn.
  8474.  
  8475.                                      Page -139-
  8476.  
  8477.  
  8478.  
  8479.  
  8480.  
  8481.                           SCL1 Version 2.0 Reference Manual
  8482.  
  8483.  
  8484.                                                            MessageShadowOff
  8485.                                                             MessageShadowOn
  8486.  
  8487.           Function:    MessageShadowOff
  8488.                        MessageShadowOn
  8489.  
  8490.           Purpose:     Displays or disable a shadow effect when using the
  8491.                        MessageOn/MessageOff functions.  After any of these
  8492.                        functions are called all subsequent calls to the
  8493.                        MessageOn function will be displayed with (or
  8494.                        without) a shadow effect.
  8495.  
  8496.           Declaration: void MessageShadowOff(void);
  8497.                        void MessageShadowOn(void);
  8498.  
  8499.           Returns:     Nothing.
  8500.  
  8501.           Parameters:  None.
  8502.  
  8503.           Example:
  8504.  
  8505.           #include <scl1.h>
  8506.           #include <scl1clor.h>
  8507.  
  8508.           main()
  8509.              {
  8510.              int i;
  8511.  
  8512.              MessageOn(WHITE_BLACK,"MessageOn function without
  8513.                                     shadow\nPress any key...");
  8514.              GetKey();
  8515.              MessageOff();
  8516.              MessageShadowOn();
  8517.              MessageOn(WHITE_BLACK,"MessageOn function WITH shadow
  8518.                                     \nPress any key...");
  8519.              GetKey();
  8520.              MessageOff();
  8521.              MessageShadowOff();
  8522.              MessageOn(WHITE_BLACK,"MessageOn function again\nwithout
  8523.                                     shadow\nPress any key...");
  8524.              GetKey();
  8525.              MessageOff();
  8526.              }
  8527.  
  8528.           See MessageOn and MessageOff.
  8529.  
  8530.  
  8531.  
  8532.  
  8533.  
  8534.                                      Page -140-
  8535.  
  8536.  
  8537.  
  8538.  
  8539.  
  8540.                           SCL1 Version 2.0 Reference Manual
  8541.  
  8542.  
  8543.                                                                 MouseButton
  8544.  
  8545.           Function:    MouseButton
  8546.  
  8547.           Purpose:     A Mouse Button is a prompt that can be placed
  8548.                        anywhere within the screen area and, when that when
  8549.                        pointed and clicked by the mouse performs a given
  8550.                        action.  It performs as a sensitive screen prompt. 
  8551.                        The selected button is drawn in the specified color
  8552.                        with or without a enclosing box. Most functions,
  8553.                        like FileBox, use Mouse Buttons (in this case to
  8554.                        select load or cancel).  If you require more than
  8555.                        one Mouse Button use the Fields2 function.
  8556.  
  8557.           Declaration: int MouseButton(int Message,MBData *p);
  8558.  
  8559.           Returns:     This is a dialog type function. See Appendix "E" for
  8560.                        a description of the general operation of these
  8561.                        functions.  The return value is a message described
  8562.                        in the Messages section.
  8563.  
  8564.           Parameters:
  8565.  
  8566.           The MouseButton information must be given in a structure, type
  8567.           MBData, as follows:
  8568.  
  8569.           Structure type MBData:
  8570.  
  8571.           typedef struct{
  8572.              int NColor;
  8573.              int RColor;
  8574.              int UpperRow;
  8575.              int LeftCol;
  8576.              int LowerRow;
  8577.              int RightCol;
  8578.              int PRow;
  8579.              int PCol;
  8580.              char *Prompt;
  8581.              int BoxFlag;
  8582.              int ActiveFlag;
  8583.              unsigned int *ExitKeys;
  8584.              unsigned int EventInfo;
  8585.              }MBData;
  8586.  
  8587.           where,
  8588.  
  8589.                 NColor - color attribute used when button is not selected
  8590.                          (integer).
  8591.  
  8592.  
  8593.                                      Page -141-
  8594.  
  8595.  
  8596.  
  8597.  
  8598.  
  8599.                           SCL1 Version 2.0 Reference Manual
  8600.  
  8601.  
  8602.                                                                 MouseButton
  8603.  
  8604.                 RColor - Color used for a selected button (integer).
  8605.  
  8606.               UpperRow - upper row coordinate of the Mouse Button area
  8607.                          (integer).
  8608.  
  8609.                LeftCol - left column coordinate of the Mouse Button area
  8610.                          (integer).
  8611.  
  8612.               LowerRow - lower row coordinate of the Mouse Button area
  8613.                          (integer).
  8614.  
  8615.               RightCol - right column coordinate of the Mouse Button area
  8616.                          (integer).
  8617.  
  8618.                   PRow - row coordinate of the Mouse Button text (integer).
  8619.  
  8620.                   PCol - column coordinate of the Mouse Button text
  8621.                          (integer).
  8622.  
  8623.                 Prompt - char pointer to the Mouse Button text.
  8624.  
  8625.                BoxFlag - a flag to indicate if a box shall be drawn around
  8626.                          a Mouse Button (integer).
  8627.  
  8628.             ActiveFlag - a flag to indicate if the Mouse Button is active
  8629.                          (integer).
  8630.  
  8631.               ExitKeys - an array of keys defined to exit the function
  8632.                          (unsigned integer).
  8633.  
  8634.              EventInfo - variable that holds the key pressed when you exit
  8635.                          the function or a non defined key is pressed
  8636.                          (unsigned integer).
  8637.           Messages:
  8638.  
  8639.           The following messages can be sent to MouseButton:
  8640.  
  8641.                         MB_INIT - initialize the MBData structure to NULL
  8642.                                   and  set the following default values:
  8643.  
  8644.                                     NColor - set to white characters in a
  8645.                                              black background or the normal
  8646.                                              color defined by calling
  8647.                                              SetDialogColors.
  8648.  
  8649.  
  8650.  
  8651.  
  8652.                                      Page -142-
  8653.  
  8654.  
  8655.  
  8656.  
  8657.  
  8658.                           SCL1 Version 2.0 Reference Manual
  8659.  
  8660.  
  8661.                                                                 MouseButton
  8662.  
  8663.                                     RColor - set to black characters in a
  8664.                                              white background or the
  8665.                                              reversed color defined by
  8666.                                              calling SetDialogColors.
  8667.  
  8668.                         MB_DRAW - display the Mouse Button.
  8669.  
  8670.                       MB_ACTIVE - move the cursor to the Mouse Button. 
  8671.                                   This message is used by the Fields2
  8672.                                   function.
  8673.  
  8674.                  MB_CHECK_MOUSE - check to see if the mouse has been
  8675.                                   clicked after pointing to the Mouse
  8676.                                   Button.
  8677.  
  8678.                        MB_RESET - when this message is sent Mouse Button
  8679.                                   variables are reset to the default value. 
  8680.                                   If the exit keys have not been defined
  8681.                                   they are set to the default exit keys.
  8682.  
  8683.           The following messages can be returned by MouseButton:
  8684.  
  8685.                           MB_OK - the function has performed the requested
  8686.                                   action.
  8687.  
  8688.                     MB_EXIT_KEY - a key that has been defined as an exit
  8689.                                   key has been pressed.
  8690.  
  8691.                  MB_MOUSE_EVENT - the mouse has been clicked after pointing
  8692.                                   outside the area defined by the function.
  8693.  
  8694.                  MB_ILLEGAL_KEY - a key that has not been defined has been
  8695.                                   pressed.
  8696.  
  8697.                 MB_MOUSE_SELECT - you have clicked your mouse after
  8698.                                   pointing to the Mouse Button.
  8699.  
  8700.                     MB_MY_MOUSE - response to a MB_CHECK_MOUSE message if
  8701.                                   the mouse has been clicked after pointing
  8702.                                   to the area defined by the function.
  8703.  
  8704.  
  8705.  
  8706.  
  8707.  
  8708.  
  8709.  
  8710.  
  8711.                                      Page -143-
  8712.  
  8713.  
  8714.  
  8715.  
  8716.  
  8717.                           SCL1 Version 2.0 Reference Manual
  8718.  
  8719.  
  8720.                                                                 MouseButton
  8721.  
  8722.           Example:
  8723.  
  8724.           #include <scl1.h>
  8725.           #include <scl1keys.h>
  8726.  
  8727.           main()
  8728.              {
  8729.              int EMess;
  8730.              MBData mb1;
  8731.  
  8732.              Cls(WHITE_BLACK,CLS_ALL);
  8733.              MouseButton(MB_INIT,&mb1);
  8734.              mb1.LeftCol=12;
  8735.              mb1.RightCol=19;
  8736.              mb1.NColor=Color1;
  8737.              mb1.RColor=Color2;
  8738.              mb1.UpperRow=6;
  8739.              mb1.Prompt="< LOAD >";;
  8740.              MouseButton(MB_DRAW,&mb1);
  8741.              do
  8742.                 {
  8743.                 EMess=MouseButton(MB_ACTIVE,&mb1);
  8744.                 }while(EMess != MB_EXIT_KEY && EMess != MB_MOUSE_SELECT);
  8745.              }
  8746.  
  8747.  
  8748.  
  8749.  
  8750.  
  8751.  
  8752.  
  8753.  
  8754.  
  8755.  
  8756.  
  8757.  
  8758.  
  8759.  
  8760.  
  8761.  
  8762.  
  8763.  
  8764.  
  8765.  
  8766.  
  8767.  
  8768.  
  8769.  
  8770.                                      Page -144-
  8771.  
  8772.  
  8773.  
  8774.  
  8775.  
  8776.                           SCL1 Version 2.0 Reference Manual
  8777.  
  8778.  
  8779.                                                                   MouseMenu
  8780.  
  8781.           Function:    MouseMenu
  8782.  
  8783.           Purpose:     Displays a scrolling or moving bar type menu.  A
  8784.                        selection is made by either pressing the highlighted
  8785.                        menu option letter, by scrolling the highlighted bar
  8786.                        using the arrow keys and then pressing the ENTER
  8787.                        (RETURN) key or by moving the mouse cursor to the
  8788.                        desired line and clicking the left mouse button. 
  8789.                        This function permits full control of the menu's
  8790.                        appearance, size and position.  The menu items can
  8791.                        be placed anywhere in the screen and in any desired
  8792.                        order, you are not limited to placing all the menu
  8793.                        options in successive lines.
  8794.  
  8795.           Declaration: int MouseMenu(int NColor, int RColor, int HColor,
  8796.                            int NumOpt, struct MenuOpt *k, int XMin,
  8797.                            int XMax, int YMin, int YMax);
  8798.  
  8799.           Returns:     The highlighted selection number (>1) or -1 if ESC
  8800.                        is pressed or if mouse is clicked outside the menu
  8801.                        area.
  8802.  
  8803.           Parameters:
  8804.  
  8805.           The menu information must be entered as an array of structures as
  8806.           follows; with one array element for each menu option:
  8807.  
  8808.              struct MenuOpt{
  8809.                 int Row,Col;
  8810.                 char *String;
  8811.                 char Letter;
  8812.                 };
  8813.  
  8814.           where:
  8815.  
  8816.                    Row - row position for the menu item (integer).
  8817.  
  8818.                    Col - column position for the menu item (integer).
  8819.  
  8820.                 String - pointer to the menu item text.
  8821.  
  8822.                 Letter - letter to be highlighted for fast keyboard
  8823.                          selection of the menu item (char).
  8824.  
  8825.  
  8826.  
  8827.  
  8828.  
  8829.                                      Page -145-
  8830.  
  8831.  
  8832.  
  8833.  
  8834.  
  8835.                           SCL1 Version 2.0 Reference Manual
  8836.  
  8837.  
  8838.                                                                   MouseMenu
  8839.  
  8840.           The parameters passed to the function are:
  8841.  
  8842.                 NColor - color attribute for the menu background and
  8843.                          foreground (integer).
  8844.  
  8845.                 RColor - color attribute for the highlighted item menu bar
  8846.                          (integer).
  8847.  
  8848.                 HColor - color attribute for the highlighted quick
  8849.                          selection menu item letter (integer).
  8850.  
  8851.                 NumOpt - number of menu options (integer).
  8852.  
  8853.                MenuOpt - pointer to the menu structure previously defined.
  8854.  
  8855.                   XMin - minimum row position of menu area (integer).
  8856.  
  8857.                   XMax - maximum row position of menu area (integer).
  8858.  
  8859.                   YMin - minimum column position of menu area (integer).
  8860.  
  8861.                   YMax - maximum column position of menu area (integer).
  8862.  
  8863.           Example:
  8864.  
  8865.           #include <scl1.h>
  8866.           #include <scl1clor.h>
  8867.  
  8868.           struct MenuOpt Mainmen[7]={/*Array of structures with seven
  8869.                                        elements */
  8870.               5,24,"Screen Related Functions    ",'S', /* First option   */
  8871.               7,24,"Keyboard Handling Functions ",'K', /* Second option  */
  8872.               9,24,"Mouse Handling Functions    ",'M', /* Third option   */
  8873.              11,24,"Program Flow Functions      ",'P', /* Fourth option  */
  8874.              13,24,"File Handling Functions     ",'F', /* Fifth option   */
  8875.              15,24,"Background and Miscellaneous",'B', /* Sixth option   */
  8876.              17,24,"Exit Demo                   ",'E', /* Seventh option */
  8877.                 };
  8878.  
  8879.  
  8880.  
  8881.  
  8882.  
  8883.  
  8884.  
  8885.  
  8886.  
  8887.  
  8888.                                      Page -146-
  8889.  
  8890.  
  8891.  
  8892.  
  8893.  
  8894.                           SCL1 Version 2.0 Reference Manual
  8895.  
  8896.  
  8897.                                                                   MouseMenu
  8898.  
  8899.           main()
  8900.              {
  8901.              int Selection;
  8902.  
  8903.              Cls(WHITE_BLACK,CLS_ALL);
  8904.              InitMouse(IM_SHOW);
  8905.              Box(WHITE_BLACK,5,1,5,18,25); /* Box for menu */
  8906.              WriteScreen(WHITE_BLACK,2,11,"FUNCTIONS"); /* Menu title */
  8907.              Selection=MouseMenu(WHITE_BLACK,BLACK_WHITE,
  8908.                 WHITE_BLACK+HIGHLIGHT,7,Mainmen,1,5,18,25);
  8909.              Cls(WHITE_BLACK,CLS_ALL);
  8910.              if(Selection > 0)
  8911.                 printf("You have selected option %i\n",Selection);
  8912.              else
  8913.                 printf("You have pressed ESCAPE or clicked the mouse
  8914.                    outside the menu area.\n");
  8915.              }
  8916.  
  8917.  
  8918.  
  8919.  
  8920.  
  8921.  
  8922.  
  8923.  
  8924.  
  8925.  
  8926.  
  8927.  
  8928.  
  8929.  
  8930.  
  8931.  
  8932.  
  8933.  
  8934.  
  8935.  
  8936.  
  8937.  
  8938.  
  8939.  
  8940.  
  8941.  
  8942.  
  8943.  
  8944.  
  8945.  
  8946.  
  8947.                                      Page -147-
  8948.  
  8949.  
  8950.  
  8951.  
  8952.  
  8953.                           SCL1 Version 2.0 Reference Manual
  8954.  
  8955.  
  8956.                                                                  MoveFilePt
  8957.  
  8958.           Function:    MoveFilePt
  8959.  
  8960.           Purpose:     Moves the file pointer to the current location plus
  8961.                        an offset.
  8962.  
  8963.           Declaration: int MoveFilePt(int Handle, unsigned long Bytes);
  8964.  
  8965.           Returns:     The return value is "0" if no error occurs or the
  8966.                        DOS error code if an error occurs.  (See Appendix
  8967.                        "A", FILE FUNCTIONS, for more information).
  8968.  
  8969.           Parameters:
  8970.  
  8971.                 Handle - number is given by DOS when you open a file
  8972.                          (integer).
  8973.  
  8974.                  Bytes - number of bytes for offset (unsigned long
  8975.                          integer).
  8976.  
  8977.           Example:
  8978.  
  8979.           #include <scl1.h>
  8980.           #include <string.h>
  8981.  
  8982.           /* This example creates a file with several names in lower-case.
  8983.           We will then open the file for appending data using MoveFilePt by
  8984.           moving the file pointer to the end of the file. */
  8985.  
  8986.           struct NAME_REC{     /* Our file format */
  8987.              char Name[7];
  8988.              }nr;              /* nr will be used as a buffer for
  8989.                                converting strings to uppercase */
  8990.           /* This is the data of the file we will create */
  8991.  
  8992.           struct NAME_REC names[]={
  8993.              "John",
  8994.              "Mary",
  8995.              "Robert",
  8996.              "Ann"};
  8997.  
  8998.           struct NAME_REC newname={"Susan"};
  8999.  
  9000.           main()
  9001.              {
  9002.              int handle;
  9003.              long filesize;
  9004.  
  9005.  
  9006.                                      Page -148-
  9007.  
  9008.  
  9009.  
  9010.  
  9011.  
  9012.                           SCL1 Version 2.0 Reference Manual
  9013.  
  9014.  
  9015.                                                                  MoveFilePt
  9016.  
  9017.              /* create file */
  9018.  
  9019.              if(Buf2Disk("DEMO.FL",(char *)names,sizeof(names)))
  9020.                 {
  9021.                 printf("Error creating file\n");
  9022.                 exit(-1);
  9023.                 }
  9024.  
  9025.              /* Open file for reading and writing */
  9026.  
  9027.              OpenFile("DEMO.FL",&handle,DOS2_RW);
  9028.  
  9029.              /* Get file size */
  9030.  
  9031.              filesize=GetFileSize(handle);
  9032.  
  9033.              /* move file pointer to end of file */
  9034.  
  9035.              MoveFilePt(handle,filesize);
  9036.  
  9037.              /* write our data */
  9038.  
  9039.              WriteFile(handle,(char *)&newname,sizeof(struct NAME_REC));
  9040.              }
  9041.           CloseFile(handle);
  9042.           }
  9043.  
  9044.           See also MoveFilePtOffset.
  9045.  
  9046.  
  9047.  
  9048.  
  9049.  
  9050.  
  9051.  
  9052.  
  9053.  
  9054.  
  9055.  
  9056.  
  9057.  
  9058.  
  9059.  
  9060.  
  9061.  
  9062.  
  9063.  
  9064.  
  9065.                                      Page -149-
  9066.  
  9067.  
  9068.  
  9069.  
  9070.  
  9071.                           SCL1 Version 2.0 Reference Manual
  9072.  
  9073.  
  9074.                                                           MoveFilePt2Offset
  9075.  
  9076.           Function:    MoveFilePt2Offset
  9077.  
  9078.           Purpose:     Moves the file read write pointer to an offset from
  9079.                        the beginning of the file.
  9080.  
  9081.           Declaration: int MoveFilePt2Offset(int Handle,
  9082.                             unsigned long Bytes);
  9083.  
  9084.           Returns:     The return value is 0 if no error occur or the DOS
  9085.                        error code if an error occur.  (See Appendix "A",
  9086.                        FILE FUNCTIONS, for more information).
  9087.  
  9088.           Parameters:
  9089.  
  9090.                 Handle - number is given by DOS when you open a file
  9091.                          (integer).
  9092.  
  9093.                  Bytes - number of bytes for offset (unsigned long
  9094.                          integer).
  9095.  
  9096.           Example:
  9097.  
  9098.           #include <scl1.h>
  9099.           #include <string.h>
  9100.  
  9101.              /* This example creates a file with several names in lower-
  9102.              case.  We will read this file one record at a time into our
  9103.              buffer and convert the string to uppercase before rewriting it
  9104.              back to disk. For simplicity, no error checking is shown in
  9105.              the example */
  9106.  
  9107.           struct NAME_REC{       /* Our file format */
  9108.                char Name[7];
  9109.                }nr;             /* nr will be used as a buffer for
  9110.                                    converting strings to uppercase */
  9111.  
  9112.           /* This is the data of the file we will create */
  9113.  
  9114.           struct NAME_REC names[]={
  9115.              "John",
  9116.              "Mary",
  9117.              "Robert",
  9118.              "Ann"};
  9119.  
  9120.  
  9121.  
  9122.  
  9123.  
  9124.                                      Page -150-
  9125.  
  9126.  
  9127.  
  9128.  
  9129.  
  9130.                           SCL1 Version 2.0 Reference Manual
  9131.  
  9132.  
  9133.                                                           MoveFilePt2Offset
  9134.  
  9135.           main()
  9136.              {
  9137.              int handle,i,j;
  9138.              long fileptr,records;
  9139.  
  9140.               /* create file */
  9141.  
  9142.              if(Buf2Disk("DEMO.FL",(char *)names,sizeof(names)))
  9143.                 {
  9144.                 printf("Error creating file\n");
  9145.                 exit(-1);
  9146.                 }
  9147.  
  9148.              /* Open file for reading and writing */
  9149.  
  9150.              OpenFile("DEMO.FL",&handle,DOS2_RW);
  9151.  
  9152.              /* number of records in file = file size / size of structure
  9153.                 NAME_REC */
  9154.  
  9155.              records=GetFileSize(handle)/sizeof(struct NAME_REC);
  9156.  
  9157.              /* read one record at a time while there are records */
  9158.              for(;records > 0;--records)
  9159.                 {
  9160.  
  9161.                 /* save actual file pointer position */
  9162.                 fileptr=GetFilePt(handle);
  9163.  
  9164.                 /* read data, file pointer is automatically moved to next
  9165.                    record by DOS */
  9166.  
  9167.                 ReadFile(handle,(char *)&nr,sizeof(struct NAME_REC));
  9168.  
  9169.                 /* capitalize name */
  9170.                 strupr(nr.Name);
  9171.  
  9172.                 /* move file pointer to original position */
  9173.                 MoveFilePt2Offset(handle,fileptr);
  9174.  
  9175.                 /* write our data, pointer points again to next record */
  9176.                 WriteFile(handle,(char *)&nr,sizeof(struct NAME_REC));
  9177.                 }
  9178.              CloseFile(handle);
  9179.              system("type DEMO.FL");
  9180.              }
  9181.           See also MoveFilePt.
  9182.  
  9183.                                      Page -151-
  9184.  
  9185.  
  9186.  
  9187.  
  9188.  
  9189.                           SCL1 Version 2.0 Reference Manual
  9190.  
  9191.  
  9192.                                                                    OpenFile
  9193.  
  9194.           Function:    OpenFile
  9195.  
  9196.           Purpose:     Opens and existing file.
  9197.  
  9198.           Declaration: int OpenFile(char *Filename, int *Handle,
  9199.                             char OMode);
  9200.  
  9201.           Returns:     The return value is "0" if no error occurs or the
  9202.                        DOS error code if an error occurs.  (See Appendix
  9203.                        "A", FILE FUNCTIONS, for more information).
  9204.  
  9205.           Parameters:
  9206.  
  9207.               Filename - pointer to filename (char).
  9208.  
  9209.                FHandle - pointer to variable that will hold DOS handle
  9210.                          number (integer).
  9211.  
  9212.                  OMode - One of several Open modes as defined in SCL1.H
  9213.                          (char):
  9214.  
  9215.                        DOS2_READ  -  For reading only.
  9216.                        DOS2_WRITE -  For writing.
  9217.                        DOS2_RW    -  For reading and writing.
  9218.  
  9219.                    Any of these modes can be used with DOS 2.0 or higher.
  9220.  
  9221.                    The following can only be used with DOS 3.0 and higher.
  9222.                    Here the Open Mode parameter is composed of three parts:
  9223.                    the Inheritance Flag, that determines if child processes
  9224.                    will inherit open files; the Sharing Mode, that
  9225.                    determines if file can be shared by several processes;
  9226.                    and the Access Mode that is similar to DOS 2.0 Open
  9227.                    Mode. You must add the three flags to get the desired
  9228.                    open mode.
  9229.  
  9230.                    Inheritance Flag:
  9231.  
  9232.                    DOS3_INHERIT   -  Child process inherit open files.
  9233.                    DOS3_PRIVATE   -  No inheritance.
  9234.  
  9235.  
  9236.  
  9237.  
  9238.  
  9239.  
  9240.  
  9241.  
  9242.                                      Page -152-
  9243.  
  9244.  
  9245.  
  9246.  
  9247.  
  9248.                           SCL1 Version 2.0 Reference Manual
  9249.  
  9250.  
  9251.                                                                    OpenFile
  9252.  
  9253.                    Sharing mode:
  9254.  
  9255.                    DOS3_COMP      -  Compatible with DOS 2.0
  9256.                    DOS3_DENY_RW   -  Deny read or write to other       
  9257.                                      processes.
  9258.                    DOS3_DENY_W    -  Deny write.
  9259.                    DOS3_DENY_R    -  Deny read.
  9260.                    DOS3_DENY_NONE -  Deny none.
  9261.  
  9262.  
  9263.                    Access mode:
  9264.                    DOS3_READ, DOS3_WRITE, DOS3_RW are similar to DOS 2.0.
  9265.  
  9266.                    See DOS 3.0 Technical Reference for more information.
  9267.  
  9268.           Example:
  9269.  
  9270.           #include <scl1.h>
  9271.  
  9272.           main()
  9273.              {
  9274.              int ErrorCode;
  9275.                 if((ErrorCode=OpenFile("FILE.1",&Handle,DOS2_RW)))
  9276.                 /* Open a file for reading & writing */
  9277.                 {
  9278.                 .  /* Error Routine */
  9279.                 .
  9280.                 }
  9281.              }
  9282.  
  9283.  
  9284.  
  9285.  
  9286.  
  9287.  
  9288.  
  9289.  
  9290.  
  9291.  
  9292.  
  9293.  
  9294.  
  9295.  
  9296.  
  9297.  
  9298.  
  9299.  
  9300.  
  9301.                                      Page -153-
  9302.  
  9303.  
  9304.  
  9305.  
  9306.  
  9307.                           SCL1 Version 2.0 Reference Manual
  9308.  
  9309.  
  9310.                                                                  PushCursor
  9311.                                                                   PopCursor
  9312.  
  9313.           Function:    PushCursor
  9314.                        PopCursor
  9315.  
  9316.           Purpose:     Saves (PushCursor) or restores (PopCursor) the
  9317.                        cursor size, shape and position.  The maximum number
  9318.                        of cursors that the function stack can hold is
  9319.                        twenty.
  9320.  
  9321.           Declaration: int PushCursor(void);
  9322.                        int PopCursor(void);
  9323.  
  9324.           Returns:     Nothing.
  9325.  
  9326.           Parameters:  None.
  9327.  
  9328.           Example:
  9329.  
  9330.           #include <scl1.h>
  9331.  
  9332.           main()
  9333.              {
  9334.              PushCursor();
  9335.              .
  9336.              .
  9337.              .
  9338.              PopCursor();
  9339.              }
  9340.  
  9341.  
  9342.  
  9343.  
  9344.  
  9345.  
  9346.  
  9347.  
  9348.  
  9349.  
  9350.  
  9351.  
  9352.  
  9353.  
  9354.  
  9355.  
  9356.  
  9357.  
  9358.  
  9359.  
  9360.                                      Page -154-
  9361.  
  9362.  
  9363.  
  9364.  
  9365.  
  9366.                           SCL1 Version 2.0 Reference Manual
  9367.  
  9368.  
  9369.                                                                     PopMenu
  9370.  
  9371.           Function:    PopMenu
  9372.  
  9373.           Purpose:     Similar to Mouse Menu but draws the menu box and
  9374.                        saves the area behind the menu box.  If the left or
  9375.                        right arrow is pressed the routine exits and returns
  9376.                        a value indicating which arrow key has been pressed.
  9377.  
  9378.           Declaration: int PopMenu(int Color,int RColor, int HColor,
  9379.                            struct PopMenuData *k);
  9380.  
  9381.           Returns:     Return values are:
  9382.  
  9383.                        "-3" if the right cursor key is pressed, "-2" if the
  9384.                        left cursor key is pressed,"-1" if ESCAPE is pressed
  9385.                        or the option number if an option key is pressed.
  9386.  
  9387.           Parameters:
  9388.  
  9389.           The menu information must be given as an array of structures as
  9390.           follows:
  9391.  
  9392.              struct PopMenuData{
  9393.                 int L1,C1,L2,C2;
  9394.                 int NumberOption;
  9395.                 char *WinBuffer;
  9396.                 struct MenuOpt *Menust;
  9397.                 };
  9398.  
  9399.           where;
  9400.  
  9401.                        L1 - upper row coordinate of the box used to enclose
  9402.                             the pull-down menu (integer).
  9403.  
  9404.                        C1 - left column coordinate of the box (integer).
  9405.  
  9406.                        L2 - lower row coordinate of the box (integer).
  9407.  
  9408.                        C2 - right column coordinate of the box (integer).
  9409.  
  9410.             NumberOptions - number of options of the pull-down menu
  9411.                             (integer).
  9412.  
  9413.                 WinBuffer - buffer to store the screen area used when
  9414.                             popping out the pull-down menu.
  9415.  
  9416.                   MenuOpt - pointer to the MenuOption structure
  9417.                             corresponding to that pull-down menu.
  9418.  
  9419.                                      Page -155-
  9420.  
  9421.  
  9422.  
  9423.  
  9424.  
  9425.                           SCL1 Version 2.0 Reference Manual
  9426.  
  9427.  
  9428.                                                                     PopMenu
  9429.  
  9430.           Example:
  9431.  
  9432.           #include <scl1.h>
  9433.           #include <scl1clor.h>
  9434.  
  9435.           struct MenuOpt Men1[]={
  9436.              2,5,"New    ",'N',
  9437.              3,5,"Open   ",'O',
  9438.              4,5,"Close  ",'C',
  9439.              5,5,"Save   ",'S',
  9440.              6,5,"Exit   ",'E',
  9441.              };
  9442.  
  9443.           struct PopMenuData pmd1[]={
  9444.              1,3,7,13,
  9445.              5,
  9446.              WinBuf1,
  9447.              Men1,
  9448.              };
  9449.  
  9450.           int Color1=WHITE_BLACK;
  9451.           int Color2=BLACK_WHITE;
  9452.           int Color3=BLACK_WHITE+HIGHLIGHT;
  9453.  
  9454.           main()
  9455.              {
  9456.              int Selection;
  9457.  
  9458.              Selection=PopMenu(Color1,Color2,Color3,pmd1);
  9459.              }
  9460.  
  9461.  
  9462.  
  9463.  
  9464.  
  9465.  
  9466.  
  9467.  
  9468.  
  9469.  
  9470.  
  9471.  
  9472.  
  9473.  
  9474.  
  9475.  
  9476.  
  9477.  
  9478.                                      Page -156-
  9479.  
  9480.  
  9481.  
  9482.  
  9483.  
  9484.                           SCL1 Version 2.0 Reference Manual
  9485.  
  9486.  
  9487.                                                                    ReadFile
  9488.  
  9489.           Function:    ReadFile
  9490.  
  9491.           Purpose:     Reads number of bytes from a file
  9492.  
  9493.           Declaration: int ReadFile(int Handle,char *Buffer,
  9494.                            unsigned int Bytes);
  9495.  
  9496.           Returns:     The return value is "0" if no error occurs or the
  9497.                        DOS error code if an error occurs.  (See Appendix
  9498.                        "A", FILE FUNCTIONS, for more information).
  9499.  
  9500.           Parameters:
  9501.  
  9502.                 Handle - handle number given by DOS when you open or create
  9503.                          a file (integer).
  9504.  
  9505.                 Buffer - pointer to the buffer that will hold the data.
  9506.  
  9507.                  Bytes - pointer to a variable that holds the number of
  9508.                          bytes to read (unsigned integer).
  9509.  
  9510.           Example:
  9511.  
  9512.           #include <scl1.h>
  9513.           #define FILE_TOO_BIG 255
  9514.  
  9515.           int File2Buf(char *FileName,char *Buffer,unsigned int * MaxSize)
  9516.           {
  9517.           int i,Handle;
  9518.           unsigned int Size;
  9519.  
  9520.           if(i=OpenFile(Filename,&Handle,DOS2_READ))
  9521.              return(i);
  9522.           if((Size=GetFileSize(Handle)> *MaxSize)
  9523.              {
  9524.              CloseFile(Handle);
  9525.              return(FILE_TOO_BIG);
  9526.              }
  9527.           if(i=ReadFile(Handle,Buffer,Size))
  9528.              {
  9529.              If(i>0)
  9530.                 CloseFile(Handle);
  9531.              return(i);
  9532.              }
  9533.           *MaxSize=Size;
  9534.           return(CloseFile(Handle));
  9535.           }
  9536.  
  9537.                                      Page -157-
  9538.  
  9539.  
  9540.  
  9541.  
  9542.  
  9543.                           SCL1 Version 2.0 Reference Manual
  9544.  
  9545.  
  9546.                                                                   RemoveDir
  9547.  
  9548.           Function:    RemoveDir
  9549.  
  9550.           Purpose:     Removes a directory
  9551.  
  9552.           Declaration: int RemoveDir(char *Path);
  9553.  
  9554.           Returns:     The return value is "0" if no error occurs or the
  9555.                        DOS error code if an error occurs.  (See Appendix
  9556.                        "A", FILE FUNCTIONS, for more information).
  9557.  
  9558.           Parameters:
  9559.  
  9560.                   Path - char pointer to directory string.
  9561.  
  9562.           Example:
  9563.  
  9564.           #include <scl1.h>
  9565.  
  9566.           main()
  9567.              {
  9568.              int ErrorCode;
  9569.  
  9570.              if((ErrorCode=RemoveDir("C:\\LETTERS")))
  9571.                 {
  9572.                 .  /* Error Routine */
  9573.                 .
  9574.                 }
  9575.              }
  9576.  
  9577.  
  9578.  
  9579.  
  9580.  
  9581.  
  9582.  
  9583.  
  9584.  
  9585.  
  9586.  
  9587.  
  9588.  
  9589.  
  9590.  
  9591.  
  9592.  
  9593.  
  9594.  
  9595.  
  9596.                                      Page -158-
  9597.  
  9598.  
  9599.  
  9600.  
  9601.  
  9602.                           SCL1 Version 2.0 Reference Manual
  9603.  
  9604.  
  9605.                                                             RemoveExtension
  9606.  
  9607.           Function:    RemoveExtension
  9608.  
  9609.           Purpose:     Removes or deletes the extension of a filename.
  9610.  
  9611.           Declaration: char *RemoveExtension(char *Filename);
  9612.  
  9613.           Returns:     The return value is a pointer to the filename
  9614.                        buffer.
  9615.  
  9616.           Parameters:
  9617.  
  9618.               Filename - char pointer to filename.
  9619.  
  9620.           Example:
  9621.  
  9622.           #include <scl1.h>
  9623.  
  9624.           char Filename[13]="FILE.C";
  9625.  
  9626.           main()
  9627.              {
  9628.              printf("%s\n",Filename);
  9629.              printf("%s\n",RemoveExtension(Filename));
  9630.              }
  9631.  
  9632.           See also ChangeExtension and AddExtension
  9633.  
  9634.  
  9635.  
  9636.  
  9637.  
  9638.  
  9639.  
  9640.  
  9641.  
  9642.  
  9643.  
  9644.  
  9645.  
  9646.  
  9647.  
  9648.  
  9649.  
  9650.  
  9651.  
  9652.  
  9653.  
  9654.  
  9655.                                      Page -159-
  9656.  
  9657.  
  9658.  
  9659.  
  9660.  
  9661.                           SCL1 Version 2.0 Reference Manual
  9662.  
  9663.  
  9664.                                                                  RenameFile
  9665.  
  9666.           Function:    RenameFile
  9667.  
  9668.           Purpose:     Renames or moves a file.
  9669.  
  9670.           Declaration: int RenameFile(char *OldName,char *NewName);
  9671.  
  9672.           Returns:     The return value is "0" if no error occurs or the
  9673.                        DOS error code if an error occurs.  (See Appendix
  9674.                        "A", FILE FUNCTIONS, for more information).
  9675.  
  9676.           Parameters:
  9677.  
  9678.                 OldName - pointer to the old filename (char).
  9679.  
  9680.                 NewName - pointer to the new filename (char).
  9681.  
  9682.           Example:
  9683.  
  9684.           #include <scl1.h>
  9685.  
  9686.           main()
  9687.              {
  9688.              int ErrorCode;
  9689.  
  9690.              if((ErrorCode=RenameFile("C:\\FILE.1","C:\\FILE.BAK")))
  9691.                 {
  9692.                 .  /* Error Routine */
  9693.                 .
  9694.                 }
  9695.              }
  9696.  
  9697.  
  9698.  
  9699.  
  9700.  
  9701.  
  9702.  
  9703.  
  9704.  
  9705.  
  9706.  
  9707.  
  9708.  
  9709.  
  9710.  
  9711.  
  9712.  
  9713.  
  9714.                                      Page -160-
  9715.  
  9716.  
  9717.  
  9718.  
  9719.  
  9720.                           SCL1 Version 2.0 Reference Manual
  9721.  
  9722.  
  9723.                                                                  ResetMouse
  9724.  
  9725.           Function:    ResetMouse
  9726.  
  9727.           Purpose:     Resets mouse to default condition (cursor hidden at
  9728.                        screen center and Interrupt service routine
  9729.                        disabled).
  9730.  
  9731.           Declaration: void ResetMouse(void);
  9732.  
  9733.           Returns:     Nothing.
  9734.  
  9735.           Parameters:  None
  9736.  
  9737.           Example:
  9738.  
  9739.           #include <scl1.h>
  9740.  
  9741.           main()
  9742.              {
  9743.  
  9744.              /* do we have a mouse? */
  9745.              if(CheckMouse())
  9746.                 {
  9747.                 /* Yes */
  9748.                 ResetMouse();  /* reset mouse */
  9749.                 SetMouseIsr(); /* initialize ISR */
  9750.                 ShowMouse();   /* cursor on */
  9751.                 }
  9752.              .
  9753.              .
  9754.              .
  9755.              ResetMouse();  /* reset mouse before exit */
  9756.              }
  9757.  
  9758.  
  9759.  
  9760.  
  9761.  
  9762.  
  9763.  
  9764.  
  9765.  
  9766.  
  9767.  
  9768.  
  9769.  
  9770.  
  9771.  
  9772.  
  9773.                                      Page -161-
  9774.  
  9775.  
  9776.  
  9777.  
  9778.  
  9779.                           SCL1 Version 2.0 Reference Manual
  9780.  
  9781.  
  9782.                                                               ResetMouseCur
  9783.  
  9784.           Function:    ResetMouseCur
  9785.  
  9786.           Purpose:     Resets mouse cursor to a block character.
  9787.  
  9788.           Declaration: void ResetMouseCur(void);
  9789.  
  9790.           Returns:     Nothing
  9791.  
  9792.           Parameters:  None
  9793.  
  9794.           Example:
  9795.  
  9796.           include <scl1.h>
  9797.           #include <scl1clor.h>
  9798.  
  9799.           main()
  9800.           {
  9801.           GSSBox(WHITE_BLACK,0,0,0,24,79,1,0,0);
  9802.           InitMouse(IM_SHOW);
  9803.           if(MSE_MouseFl)
  9804.              {
  9805.              SetMouseCur('*');
  9806.              WriteScreenLen(WHITE_BLACK+HIGHLIGHT,23,2,40,"Mouse cursor
  9807.                             set to '*' character");
  9808.              WaitTime(300);
  9809.              ResetMouseCur();
  9810.              WriteScreenLen(WHITE_BLACK+HIGHLIGHT,23,2,40,"Mouse cursor
  9811.                             reset to normal");
  9812.              WaitTime(300);
  9813.              }
  9814.           else
  9815.              WriteScreenLen(WHITE_BLACK+HIGHLIGHT,23,2,40,"No mouse
  9816.                             installed.");
  9817.           }
  9818.  
  9819.  
  9820.  
  9821.  
  9822.  
  9823.  
  9824.  
  9825.  
  9826.  
  9827.  
  9828.  
  9829.  
  9830.  
  9831.  
  9832.                                      Page -162-
  9833.  
  9834.  
  9835.  
  9836.  
  9837.  
  9838.                           SCL1 Version 2.0 Reference Manual
  9839.  
  9840.  
  9841.                                                                  ScreenDump
  9842.  
  9843.           Function:    ScreenDump
  9844.  
  9845.           Purpose:     Displays a screendump array in the screen.  The
  9846.                        screendump array consists of characters followed by
  9847.                        its color attribute byte, terminated with a "0".
  9848.  
  9849.           Declaration: void ScreenDump(int Row, int Column, char *Array);
  9850.  
  9851.           Returns:     Nothing
  9852.            
  9853.           Parameters:
  9854.  
  9855.                    Row - row position for the array display (integer).
  9856.  
  9857.                 Column - column position for array display (integer).
  9858.  
  9859.                  Array - pointer to the array buffer (char).
  9860.  
  9861.           Example:
  9862.  
  9863.           #include <scl1.h>
  9864.  
  9865.           char Array[]={'A',7,'B',0x70,\n,'C',0x70,'D',7,0};
  9866.  
  9867.           main()
  9868.              {
  9869.              /* Each character is followed by its color attribute, a \n can
  9870.                 be used to indicate end of lines and a "0" must be used to
  9871.                 indicate the end of the array */
  9872.  
  9873.                 ScreenDump(10,10,Array); /* Write at line 10, column 10 */
  9874.                 GetKey();
  9875.  
  9876.                 ChangeDumpColor(0x70,7,Array);
  9877.                 ScreenDump(10,10,Array); /* Write at line 10, column 10 */
  9878.                 /* Change all character attributes 0x17 to 7 */
  9879.              }
  9880.  
  9881.           Notes:   The array must be null terminated, \n is used to
  9882.                    indicate end of lines.
  9883.  
  9884.           See also ChangeDumpColor.
  9885.  
  9886.  
  9887.  
  9888.  
  9889.  
  9890.  
  9891.                                      Page -163-
  9892.  
  9893.  
  9894.  
  9895.  
  9896.  
  9897.                           SCL1 Version 2.0 Reference Manual
  9898.  
  9899.  
  9900.                                                                  ScrollDown
  9901.  
  9902.           Function:    ScrollDown
  9903.  
  9904.           Purpose:     Scrolls down a screen area.
  9905.  
  9906.           Declaration: void ScrollDown(int Color, int UpperRow,
  9907.                             int LeftCol, int LowerRow, int RightCol,
  9908.                             int Scroll);
  9909.  
  9910.           Returns:     Nothing
  9911.  
  9912.           Parameters:
  9913.  
  9914.                  Color - color attribute of the area to be scrolled
  9915.                          (integer).
  9916.  
  9917.               UpperRow - upper row coordinate of the area to be scrolled
  9918.                          (integer).
  9919.  
  9920.                LeftCol - left column coordinate of the area to be scrolled
  9921.                          (integer).
  9922.  
  9923.               LowerRow - lower row coordinate of the area to be scrolled
  9924.                          (integer).
  9925.  
  9926.               RightCol - right column coordinate of the area to be scrolled
  9927.                          (integer).
  9928.  
  9929.                 Scroll - number of lines to scroll, if this variable is set
  9930.                          to "0" the whole window is cleared (integer).
  9931.  
  9932.           Example:
  9933.  
  9934.              ScrollDown(Color1,18,0,24,79,1);
  9935.  
  9936.  
  9937.  
  9938.  
  9939.  
  9940.  
  9941.  
  9942.  
  9943.  
  9944.  
  9945.  
  9946.  
  9947.  
  9948.  
  9949.  
  9950.                                      Page -164-
  9951.  
  9952.  
  9953.  
  9954.  
  9955.  
  9956.                           SCL1 Version 2.0 Reference Manual
  9957.  
  9958.  
  9959.                                                                  ScrollList
  9960.  
  9961.           Function:    ScrollList
  9962.  
  9963.           Purpose:     Displays a list of items enclosed in a box.  Only
  9964.                        the number of items desired are displayed.  The
  9965.                        function permits to scroll through the items using
  9966.                        the arrow keys or the mouse.  Pressing the ENTER key
  9967.                        or clicking the mouse in a highlighted item selects
  9968.                        the desired item.
  9969.  
  9970.           Declaration: int ScrollList(int NColor, int RColor,
  9971.                            int Row, int Col, int Lines,char **p);
  9972.  
  9973.           Returns:     The return value is the selected item's number or 
  9974.                        "-1" if the ESC key is pressed.
  9975.  
  9976.           Parameters:
  9977.  
  9978.           The scroll list information must be given in a null terminated
  9979.           char pointer array as follows:
  9980.  
  9981.                 char * ScrollDat[]
  9982.  
  9983.           The parameters passed to the function are:
  9984.  
  9985.                 NColor - color attribute for the normal display of items
  9986.                          (integer).
  9987.  
  9988.                 RColor - color attribute for the highlighted item
  9989.                          (integer).
  9990.  
  9991.                    Row - row position for the display of the first item of
  9992.                          the scroll list (integer).
  9993.  
  9994.                    Col - column position for the display of the first item
  9995.                          of the scroll list (integer).
  9996.  
  9997.                  Lines - number of lines to display in the box (integer).
  9998.  
  9999.                      p - char pointer to the ScrollList structure.
  10000.  
  10001.  
  10002.  
  10003.  
  10004.  
  10005.  
  10006.  
  10007.  
  10008.  
  10009.                                      Page -165-
  10010.  
  10011.  
  10012.  
  10013.  
  10014.  
  10015.                           SCL1 Version 2.0 Reference Manual
  10016.  
  10017.  
  10018.                                                                  ScrollList
  10019.  
  10020.           Example:
  10021.  
  10022.           #include <scl1.h>
  10023.           #include <scl1clor.h>
  10024.  
  10025.           int Color1=WHITE_BLACK;
  10026.           int Color2=BLACK_WHITE;
  10027.  
  10028.           /* ScrollList pointer structure */
  10029.                 char *Slist[]={
  10030.                 "Copy File   ",
  10031.                 "Sort File   ",
  10032.                 "Move File   ",
  10033.                 "Merge Files ",
  10034.                 "Delete File ",
  10035.                 "Tag File    ",
  10036.                 "Erase File  ",
  10037.                 "Append Files",
  10038.                 "Browse File ",
  10039.                 "Insert File ",
  10040.                 0};
  10041.  
  10042.           main()
  10043.              {
  10044.              int Selection;
  10045.  
  10046.              Selection=ScrollList(Color1,Color2,5,40,5,(int*)Slist);
  10047.              }
  10048.  
  10049.  
  10050.  
  10051.  
  10052.  
  10053.  
  10054.  
  10055.  
  10056.  
  10057.  
  10058.  
  10059.  
  10060.  
  10061.  
  10062.  
  10063.  
  10064.  
  10065.  
  10066.  
  10067.  
  10068.                                      Page -166-
  10069.  
  10070.  
  10071.  
  10072.  
  10073.  
  10074.                           SCL1 Version 2.0 Reference Manual
  10075.  
  10076.  
  10077.                                                                    ScrollUp
  10078.  
  10079.           Function:    ScrollUp
  10080.  
  10081.           Purpose:     Scrolls up a screen area.
  10082.  
  10083.           Declaration: void ScrollUp(int Color, int UpperRow, int LeftCol,
  10084.                             int LowerRow,int RightCol, int Scroll);
  10085.  
  10086.           Returns:     Nothing
  10087.  
  10088.           Parameters:
  10089.  
  10090.                  Color - color attribute of the area to be scrolled
  10091.                          (integer).
  10092.  
  10093.               UpperRow - upper row coordinate of the area to be scrolled
  10094.                          (integer).
  10095.  
  10096.                LeftCol - left column coordinate of the area to be scrolled
  10097.                          (integer).
  10098.  
  10099.               LowerRow - lower row coordinate of the area to be scrolled
  10100.                          (integer).
  10101.  
  10102.               RightCol - right column coordinate of the area to be scrolled
  10103.                          (integer).
  10104.  
  10105.                 Scroll - number of lines to scroll, if this variable is set
  10106.                          to "0" the whole window is cleared.
  10107.  
  10108.           Example:
  10109.  
  10110.              ScrollUp(Color1,18,0,24,79,1);
  10111.  
  10112.  
  10113.  
  10114.  
  10115.  
  10116.  
  10117.  
  10118.  
  10119.  
  10120.  
  10121.  
  10122.  
  10123.  
  10124.  
  10125.  
  10126.  
  10127.                                      Page -167-
  10128.  
  10129.  
  10130.  
  10131.  
  10132.  
  10133.                           SCL1 Version 2.0 Reference Manual
  10134.  
  10135.  
  10136.                                                                ScrollWindow
  10137.  
  10138.           Function:    ScrollWindow
  10139.  
  10140.           Purpose:     Displays a window with a list of items.  If the list
  10141.                        is larger than the window, or if a item's length is
  10142.                        larger than the display width, you can scroll the
  10143.                        display area both horizontally and vertically to
  10144.                        show all the information.  The window can have
  10145.                        scroll bars in both the right side and the bottom to
  10146.                        show the relative position of the text within the
  10147.                        window. The function permits you to scroll through
  10148.                        the items using the cursor keys or the mouse. 
  10149.                        Pressing the SPACEBAR or clicking the mouse after
  10150.                        pointing to an item tags or untags the desired item. 
  10151.                        This is a dialog type function.  To select an item
  10152.                        press the ENTER key or double click the mouse after
  10153.                        pointing to the item.
  10154.  
  10155.           Declaration: int ScrollWindow(int Message,SWData *p,...)
  10156.  
  10157.           Returns:     This is a dialog type function. See Appendix "E" for
  10158.                        a description of the general operation of these
  10159.                        functions.  The return value is a message described
  10160.                        in the Messages section.
  10161.  
  10162.           Parameters:
  10163.  
  10164.           The scroll window information must be given in a structure
  10165.           defined as type SWData. The structure elements are as follows:
  10166.  
  10167.           SWData type structure:
  10168.  
  10169.           typedef struct{
  10170.              int NColor;
  10171.              int RColor;
  10172.              int UpperRow;
  10173.              int LeftCol;
  10174.              int LowerRow;
  10175.              int RightCol;
  10176.              int FrameType;
  10177.              int ScrollBar;
  10178.              int BarColor;
  10179.              char **Array;
  10180.              char *TagArray;
  10181.              int TagColor;
  10182.              char *Title;
  10183.              int TitleColor;
  10184.              unsigned int *ExitKeys;
  10185.  
  10186.                                      Page -168-
  10187.  
  10188.  
  10189.  
  10190.  
  10191.  
  10192.                           SCL1 Version 2.0 Reference Manual
  10193.  
  10194.  
  10195.                                                                ScrollWindow
  10196.  
  10197.              unsigned int Lines;
  10198.              unsigned int Length;
  10199.              unsigned int TopLine;
  10200.              unsigned int Position;
  10201.              unsigned int FirstCol;
  10202.              int OldVBlock;
  10203.              int OldHBlock;
  10204.              int WindowLines;
  10205.              int WindowCols;
  10206.              int VScroll;
  10207.              int HScroll;
  10208.              unsigned int EventInfo;
  10209.              }SWData;
  10210.  
  10211.           where;
  10212.  
  10213.                 NColor - color attribute for normal display (integer).
  10214.  
  10215.                 RColor - color attributes for reversed display (integer).
  10216.  
  10217.               UpperRow - upper row coordinate of the window (integer).
  10218.  
  10219.                LeftCol - left column coordinate of the window (integer).
  10220.  
  10221.               LowerRow - lower row coordinate of the window (integer).
  10222.  
  10223.               RightCol - right column coordinate of the window (integer).
  10224.  
  10225.              FrameType - any of the frame types that can be used with the
  10226.                          Box or GSSbox functions (integer).
  10227.  
  10228.              ScrollBar - a flag to signal the function to draw scroll bars
  10229.                          to indicate the relative position of the cursor
  10230.                          within the array length (integer).
  10231.  
  10232.               BarColor - color attributes for the scroll bars (integer).
  10233.  
  10234.                  Array - pointer to a null terminated array of pointers to
  10235.                          be displayed.
  10236.  
  10237.               TagArray - an array that holds which item has been tagged. 
  10238.                          If a null pointer is specified the function will
  10239.                          not permit tagging.  An array element value of "0"
  10240.                          and "1"  indicate the status for untagged and
  10241.                          tagged (char).
  10242.  
  10243.  
  10244.  
  10245.                                      Page -169-
  10246.  
  10247.  
  10248.  
  10249.  
  10250.  
  10251.                           SCL1 Version 2.0 Reference Manual
  10252.  
  10253.  
  10254.                                                                ScrollWindow
  10255.  
  10256.               TagColor - color attributes to be used for displaying a
  10257.                          tagged item (integer).
  10258.  
  10259.                  Title - char pointer to text to be displayed in the
  10260.                          window's top row as a title.
  10261.  
  10262.             TitleColor - color attributes for the title's display
  10263.                          (integer).
  10264.  
  10265.               ExitKeys - an array of keys defined to exit the function
  10266.                          (unsigned integer).
  10267.  
  10268.                  Lines - structure element (used internally) that holds the
  10269.                          quantity of items in the array (unsigned integer).
  10270.  
  10271.                 Length - structure element (used internally) that holds the
  10272.                          length of the longest element in the ScrollWindow
  10273.                          array (unsigned integer).
  10274.  
  10275.                TopLine - structure element (used internally) that holds the
  10276.                          element number that is being displayed in the
  10277.                          first line of the window (unsigned integer).
  10278.  
  10279.               Position - structure element (used internally) that holds the
  10280.                          active position of the display (unsigned integer). 
  10281.                          Note this element should not be modified by the
  10282.                          calling program.
  10283.  
  10284.               FirstCol - structure element (used internally) that holds the
  10285.                          horizontal offset of the window.  If there is no
  10286.                          horizontal scroll, its value is "0".  When there
  10287.                          is scroll the value will be the number of columns
  10288.                          to the left of the first column displayed
  10289.                          (unsigned integer).
  10290.  
  10291.             OldVHBlock - structure element (used internally) that holds the
  10292.                          position of the vertical relative position
  10293.                          indicating scroll bar block (integer).
  10294.  
  10295.             OldVHBlock - structure element (used internally) that holds the
  10296.                          position of the horizontal relative position
  10297.                          indicating scroll bar block (integer).
  10298.  
  10299.            WindowLines - structure element (used internally) that holds the
  10300.                          number of lines in the List Window (integer).
  10301.  
  10302.  
  10303.  
  10304.                                      Page -170-
  10305.  
  10306.  
  10307.  
  10308.  
  10309.  
  10310.                           SCL1 Version 2.0 Reference Manual
  10311.  
  10312.  
  10313.                                                                ScrollWindow
  10314.  
  10315.             WindowCols - structure element (used internally) that holds the
  10316.                          number of columns in the List Window (integer).
  10317.  
  10318.                VScroll - structure element (used internally) that keeps
  10319.                          track if vertical scroll is required (integer).
  10320.  
  10321.                HScroll - structure element (used internally) that keeps
  10322.                          track if horizontal scroll is required (integer).
  10323.  
  10324.              EventInfo - information about the keys that have been pressed
  10325.                          (unsigned integer).
  10326.  
  10327.           Messages:
  10328.  
  10329.           The messages that can be sent to the ScrollWindow function are:
  10330.  
  10331.                         SW_INIT - Initialize the SWData structure to its
  10332.                                   default values.  The default values are:
  10333.  
  10334.                                     NColor - set to white characters in a
  10335.                                              black background or the normal
  10336.                                              color defined by calling
  10337.                                              SetDialogColors.
  10338.  
  10339.                                     RColor - set to black characters in a
  10340.                                              white background or the
  10341.                                              reversed color defined by
  10342.                                              calling SetDialogColors.
  10343.  
  10344.                                   LowerRow - one row less than the screen
  10345.                                              length.
  10346.  
  10347.                                   RightCol - one column less than the
  10348.                                              screen width.
  10349.  
  10350.                                  FrameType - set to frame type "1" (single
  10351.                                              line).
  10352.  
  10353.                                  ScrollBar - set to draw scroll bars.
  10354.  
  10355.                                   BarColor - set to black characters in a
  10356.                                              white background or the
  10357.                                              reversed color defined by
  10358.                                              calling SetDialogColors.
  10359.  
  10360.  
  10361.  
  10362.  
  10363.                                      Page -171-
  10364.  
  10365.  
  10366.  
  10367.  
  10368.  
  10369.                           SCL1 Version 2.0 Reference Manual
  10370.  
  10371.  
  10372.                                                                ScrollWindow
  10373.  
  10374.                                   TagColor - set to black characters in a
  10375.                                              white background or the
  10376.                                              reversed color defined by
  10377.                                              calling SetDialogColors.
  10378.  
  10379.                                 TitleColor - set to white characters in a
  10380.                                              black background or the normal
  10381.                                              color defined by calling
  10382.                                              SetDialogColors.
  10383.  
  10384.                                  OldVBlock - set to "1".
  10385.  
  10386.                                  OldHBlock - set to "1".
  10387.  
  10388.                         SW_DRAW - display the Scroll Window with the
  10389.                                   current information.
  10390.  
  10391.                        SW_WRITE - write the items to the screen.
  10392.  
  10393.                       SW_ACTIVE - browse through the displayed items and
  10394.                                   permit the selection or tagging of them
  10395.                                   using the cursor movement keys as
  10396.                                   follows:
  10397.  
  10398.                          Key                      action
  10399.  
  10400.                        Up Arrow         cursor one item up.
  10401.                        Down Arrow       cursor one item down.
  10402.                        END              cursor to end of file list.
  10403.                        HOME             cursor to beginning of list.
  10404.                        Page Up          cursor one screen up.
  10405.                        Page Down        cursor one screen down.
  10406.  
  10407.                  SW_DRAW_BORDER - draw the Scroll Window's border.
  10408.  
  10409.               SW_POSITION_BEGIN - move cursor to the first item.
  10410.  
  10411.                 SW_POSITION_END - move cursor to the last item.
  10412.  
  10413.                  SW_POSITION_UP - move cursor to the previous item.
  10414.  
  10415.                SW_POSITION_DOWN - move cursor to the next item.
  10416.  
  10417.                 SW_SET_POSITION - move cursor to a specific item.  The item
  10418.                                   number is passed as a parameter.
  10419.  
  10420.                          SW_CLS - clear the list window.
  10421.  
  10422.                                      Page -172-
  10423.  
  10424.  
  10425.  
  10426.  
  10427.  
  10428.                           SCL1 Version 2.0 Reference Manual
  10429.  
  10430.  
  10431.                                                                ScrollWindow
  10432.  
  10433.                  SW_CHECK_MOUSE - check if the mouse has been clicked after
  10434.                                   pointing to the area defined by the
  10435.                                   function.
  10436.  
  10437.                      SW_UWRITE -  recalculate all the internal variables
  10438.                                   but do not write the Scroll Window unless
  10439.                                   the display contents has changed.
  10440.  
  10441.                        SW_RESET - when this message is sent the position
  10442.                                   variables are reset to the default value. 
  10443.                                   If the exit keys have not been defined
  10444.                                   they are set to the default exit keys.
  10445.  
  10446.           The messages returned by ScrollWindow are:
  10447.  
  10448.                   SW_NULL_ARRAY - no item array has been defined.
  10449.  
  10450.                           SW_OK - the requested action has been performed.
  10451.  
  10452.                     SW_EXIT_KEY - a defined exit key has been pressed.
  10453.  
  10454.                  SW_MOUSE_EVENT - the mouse has been clicked but it has not
  10455.                                   been pointed to the area defined by the
  10456.                                   function.
  10457.  
  10458.                   SW_BUFFER_END - you have requested to move the cursor
  10459.                                   passed the last item.
  10460.  
  10461.                 SW_BUFFER_BEGIN - you have requested to move the cursor up
  10462.                                   and you have the first item active.
  10463.  
  10464.                  SW_ILLEGAL_KEY - an undefined key has been pressed.
  10465.  
  10466.             SW_ILLEGAL_POSITION - you have requested to move the cursor to
  10467.                                   an invalid position.
  10468.  
  10469.                 SW_NEW_POSITION - the cursor position has been updated.
  10470.  
  10471.                 SW_MOUSE_SELECT - one of the elements have been selected by
  10472.                                   double clicking the mouse.
  10473.  
  10474.                     SW_MY_MOUSE - response to a SW_CHECK_MOUSE message if
  10475.                                   the mouse has been clicked after pointing
  10476.                                   to the area defined by the function.
  10477.  
  10478.  
  10479.  
  10480.  
  10481.                                      Page -173-
  10482.  
  10483.  
  10484.  
  10485.  
  10486.  
  10487.                           SCL1 Version 2.0 Reference Manual
  10488.  
  10489.  
  10490.                                                                ScrollWindow
  10491.  
  10492.                 SW_NEW_MOUSEPOS - you have moved the cursor by clicking the
  10493.                                   mouse after pointing to an item.
  10494.  
  10495.                   SW_BLOCK_MARK - this message is returned when you have
  10496.                                   marked a series of items by dragging you
  10497.                                   mouse after clicking at an item.
  10498.  
  10499.           Example:
  10500.  
  10501.           #include <scl1.h>
  10502.           #include <scl1clor.h>
  10503.           #include <scl1keys.h>
  10504.  
  10505.           int Color1=WHITE_BLACK;
  10506.  
  10507.           char *Info={"",
  10508.           " BigCursor         - Changes the cursor size to a block.",
  10509.           "",
  10510.           " Center            - Centers a string horizontally.",
  10511.           "",
  10512.           " Cls               - Clears a screen area.",
  10513.           "",
  10514.           " CursorOff         - Turns the cursor off.",
  10515.           "",
  10516.           " CursorOn          - Turns the cursor on (cursor visible).",
  10517.           "",
  10518.           " DrawItemList      - Draws an item list to the screen.",
  10519.           "",
  10520.           " GetCurLine        - Returns the current cursor row position.",
  10521.           "",
  10522.           " GetCurSize        - Returns the current cursor size.",
  10523.           "",
  10524.           " ScrollUp          - Scrolls up a screen area.",
  10525.           "",
  10526.           " SetCurPos         - Sets the cursor position.",
  10527.           "",
  10528.           " SetCurSize        - Sets the cursor size.",
  10529.           "",
  10530.           " SetVideoMode      - Sets the video mode.",
  10531.           "",
  10532.           " SetVideoPage      - Sets the video page.",
  10533.           "",
  10534.           " SetVideo25        - Sets the display mode to 25 lines.",
  10535.           "",
  10536.           " Shadow            - Draws a shadow effect to a screen area.",
  10537.           "",
  10538.  
  10539.  
  10540.                                      Page -174-
  10541.  
  10542.  
  10543.  
  10544.  
  10545.  
  10546.                           SCL1 Version 2.0 Reference Manual
  10547.  
  10548.  
  10549.                                                                ScrollWindow
  10550.  
  10551.           " Video             - Detects if the video adapter in use is",
  10552.           "                     either Monochrome, CGA or EGA.",
  10553.           "",
  10554.           " WriteCharBlock    - Writes a block of characters.",
  10555.           "",
  10556.           " WriteOffset       - Writes a character at a given offset.",
  10557.           "",
  10558.           " Window            - Saves, clears and restores a window.",
  10559.           ,0};
  10560.  
  10561.           unsigned int ExitK[]={ESC,ENTER,0};
  10562.  
  10563.           main
  10564.           {
  10565.           int i;
  10566.           SWData sw;  /* Use the default Scroll Window structure */
  10567.  
  10568.           CursorOff();                  /* Turn of cursor         */
  10569.           InitMouse(IM_SHOW);
  10570.           Cls(Color1,CLS_ALL);
  10571.           ScrollWindow(SW_INIT,&sw);    /* Initialize Scroll Window */
  10572.  
  10573.           sw.UpperRow=2;                /* Change default window size */
  10574.           sw.LeftCol=4;
  10575.           sw.LowerRow=22;
  10576.           sw.RightCol=75;
  10577.           sw.NColor=0x70;               /* Change default color     */
  10578.           sw.RColor=0x7f;               /* Do not show scroll bar   */
  10579.           sw.ExitKeys=ExitK;
  10580.           sw.Array=Info;
  10581.           sw.Title="[ Information ]";
  10582.           sw.TitleColor=0x70;
  10583.           SetShadowColor(8);            /* We want an Xor shadow    */
  10584.           Shadow(0,2,4,22,75);          /* Around Scroll Window     */
  10585.           ScrollWindow(SW_DRAW,&sw);    /* Now, draw the Scroll Window */
  10586.             do                          /* Browse window until an exit key
  10587.                                         is pressed*/
  10588.             {
  10589.               i=ScrollWindow(SW_ACTIVE,&sw);
  10590.  
  10591.             }while(i!=SW_EXIT_KEY && i!=SW_MOUSE_EVENT);
  10592.           CursorOn();
  10593.           }
  10594.  
  10595.  
  10596.  
  10597.  
  10598.  
  10599.                                      Page -175-
  10600.  
  10601.  
  10602.  
  10603.  
  10604.  
  10605.                           SCL1 Version 2.0 Reference Manual
  10606.  
  10607.  
  10608.                                                                      Select
  10609.  
  10610.           Function:    Select
  10611.  
  10612.           Purpose:     Will permit the display of various options and let
  10613.                        the user to select one of them.  To move among
  10614.                        options the user can use the arrow keys.  A
  10615.                        selection can be made by clicking the left mouse
  10616.                        button after pointing to the desired option or by
  10617.                        pressing a key defined as an exit key.  The active
  10618.                        option will be displayed with a check mark between
  10619.                        parenthesis (√).  This is a dialog type function
  10620.                        that can either be used alone or as one of the field
  10621.                        types for the fields option.
  10622.  
  10623.           Declaration: int Select(int Message,SData1 *sd1,SData2 *sd2)
  10624.  
  10625.           Returns:     This is a dialog type function. See Appendix "E" for
  10626.                        a description of the general operation of these
  10627.                        functions.  The return value is a message described
  10628.                        in the Messages section.
  10629.  
  10630.           Parameters:
  10631.  
  10632.           The options must be passed as a null terminated array of
  10633.           structures of the type SData1, one array element for each select
  10634.           option:
  10635.  
  10636.           typedef struct{
  10637.              int Row;
  10638.              int Col;
  10639.              char *String;
  10640.              }SData1;
  10641.  
  10642.           where,
  10643.  
  10644.                    Row - row position where the option is displayed
  10645.                          (integer).
  10646.  
  10647.                    Col - column position where the option is displayed
  10648.                          (integer).
  10649.  
  10650.                 String - char pointer to the text used to identify the
  10651.                          option.
  10652.  
  10653.  
  10654.  
  10655.  
  10656.  
  10657.  
  10658.                                      Page -176-
  10659.  
  10660.  
  10661.  
  10662.  
  10663.  
  10664.                           SCL1 Version 2.0 Reference Manual
  10665.  
  10666.  
  10667.                                                                      Select
  10668.  
  10669.           The general information about the Select options are included in
  10670.           a structure type SData2, as follows:
  10671.  
  10672.           typedef struct{
  10673.              int Color;
  10674.              int PRow;
  10675.              int PCol;
  10676.              char *Prompt;
  10677.              unsigned int *ExitKeys;
  10678.              int Options;
  10679.              int Position;
  10680.              unsigned int EventInfo;
  10681.              }SData2;
  10682.  
  10683.           where,
  10684.  
  10685.                  Color - color attributes for the display of the select
  10686.                          options (integer).
  10687.  
  10688.                   PRow - row position where to display an optional prompt
  10689.                          or select options title (integer).
  10690.  
  10691.                   PCol - column position where to display an optional
  10692.                          prompt or select options title (integer).
  10693.  
  10694.                 Prompt - char pointer to an optional prompt or select
  10695.                          options title.
  10696.  
  10697.               ExitKeys - array of keys defined as exit keys (unsigned
  10698.                          integer).
  10699.  
  10700.                Options - number of options available (integer).
  10701.  
  10702.               Position - default selection (integer).
  10703.  
  10704.              EventInfo - this structure element will hold the last illegal
  10705.                          or exit key pressed (unsigned integer).
  10706.  
  10707.           Messages:
  10708.  
  10709.           The messages that can be sent to the Select are:
  10710.  
  10711.                          S_INIT - initialize the SData2 structure to NULL
  10712.                                   (the SData1 structure must be initialized
  10713.                                   with the position and text information)
  10714.                                   and set the following default values:
  10715.  
  10716.  
  10717.                                      Page -177-
  10718.  
  10719.  
  10720.  
  10721.  
  10722.  
  10723.                           SCL1 Version 2.0 Reference Manual
  10724.  
  10725.  
  10726.                                                                      Select
  10727.  
  10728.                                 Color - set to black characters in a white
  10729.                                         background or the reversed color
  10730.                                         defined by calling SetDialogColors.
  10731.  
  10732.                              ExitKeys - ENTER, ESC, TAB and SHIFT TAB.
  10733.  
  10734.                          S_DRAW - draws the Select display.
  10735.  
  10736.                        S_ACTIVE - activates the function.
  10737.  
  10738.                   S_CHECK_MOUSE - check if the mouse has been clicked after
  10739.                                   pointing to the area defined by the
  10740.                                   function.
  10741.  
  10742.                         S_RESET - when this message is sent the position
  10743.                                   variables are reset to the default value. 
  10744.                                   If the exit keys have not been defined
  10745.                                   they are set to the default exit keys.
  10746.  
  10747.           The following messages can be returned by Select:
  10748.  
  10749.                    S_NULL_ARRAY - no select item array has been defined.
  10750.  
  10751.                            S_OK - action requested was performed.
  10752.  
  10753.                      S_EXIT_KEY - a key defined as an exit key has been
  10754.                                   pressed.
  10755.  
  10756.                   S_MOUSE_EVENT - the mouse has been clicked but it has not
  10757.                                   been pointed to the area defined by the
  10758.                                   function.
  10759.  
  10760.                   S_ILLEGAL_KEY - an illegal key has been pressed.
  10761.  
  10762.                  S_NEW_POSITION - the cursor position has been updated.
  10763.  
  10764.                      S_MY_MOUSE - response to a S_CHECK_MOUSE message if
  10765.                                   the mouse has been clicked after pointing
  10766.                                   to the area defined by the function.
  10767.  
  10768.  
  10769.  
  10770.  
  10771.  
  10772.  
  10773.  
  10774.  
  10775.  
  10776.                                      Page -178-
  10777.  
  10778.  
  10779.  
  10780.  
  10781.  
  10782.                           SCL1 Version 2.0 Reference Manual
  10783.  
  10784.  
  10785.                                                                      Select
  10786.  
  10787.           Example:
  10788.  
  10789.           #include <scl1.h>
  10790.           #include <scl1keys.h>
  10791.           #include <scl1clor.h>
  10792.  
  10793.           unsigned int ExitKeys[]={ESC,ENTER,0};
  10794.  
  10795.           SData1 sd1[]={
  10796.              12,35,"Male",
  10797.              13,35,"Female",
  10798.              0};
  10799.  
  10800.           SData2 sd2={WHITE_BLACK,10,32,"Enter your sex:",ExitKeys,0,0,0};
  10801.  
  10802.           main()
  10803.           {
  10804.           int Mess;
  10805.  
  10806.           InitVideo();
  10807.           Select(S_RESET,sd1,&sd2);
  10808.           Select(S_DRAW,sd1,&sd2);
  10809.           do
  10810.              {
  10811.              Mess=Select(S_ACTIVE,sd1,&sd2);
  10812.              }while(Mess!=S_EXIT_KEY);
  10813.           }
  10814.  
  10815.  
  10816.  
  10817.  
  10818.  
  10819.  
  10820.  
  10821.  
  10822.  
  10823.  
  10824.  
  10825.  
  10826.  
  10827.  
  10828.  
  10829.  
  10830.  
  10831.  
  10832.  
  10833.  
  10834.  
  10835.                                      Page -179-
  10836.  
  10837.  
  10838.  
  10839.  
  10840.  
  10841.                           SCL1 Version 2.0 Reference Manual
  10842.  
  10843.  
  10844.                                                                   SetCurPos
  10845.  
  10846.           Function:    SetCurPos
  10847.  
  10848.           Purpose:     Sets the cursor position.
  10849.  
  10850.           Declaration: void SetCurPos(int Row, int Col);
  10851.  
  10852.           Returns:     Nothing
  10853.  
  10854.           Parameters:
  10855.  
  10856.                    Row - the desired row position coordinate (integer).
  10857.  
  10858.                    Col - the desired column position coordinate (integer).
  10859.  
  10860.           Example:
  10861.  
  10862.           #include <scl1.h>
  10863.           #include <scl1clor.h>
  10864.  
  10865.           main()
  10866.              {
  10867.              InitVideo();
  10868.  
  10869.              SetCurPos(10,20);
  10870.              printf("Cursor was moved to position 10,20");
  10871.              WaitTime(200);
  10872.              SetCurPos(20,40);
  10873.              printf("Cursor was moved to position 20,40");
  10874.              WaitTime(200);
  10875.              SetCurPos(0,0);
  10876.              printf("Cursor was moved to position 0,0");
  10877.              }
  10878.  
  10879.  
  10880.  
  10881.  
  10882.  
  10883.  
  10884.  
  10885.  
  10886.  
  10887.  
  10888.  
  10889.  
  10890.  
  10891.  
  10892.  
  10893.  
  10894.                                      Page -180-
  10895.  
  10896.  
  10897.  
  10898.  
  10899.  
  10900.                           SCL1 Version 2.0 Reference Manual
  10901.  
  10902.  
  10903.                                                                  SetCurSize
  10904.  
  10905.           Function:    SetCurSize
  10906.  
  10907.           Purpose:     Sets the cursor size.
  10908.  
  10909.           Declaration: void SetCurSize(int CursorSize);
  10910.  
  10911.           Returns:     Nothing
  10912.  
  10913.           Parameters:
  10914.  
  10915.             CursorSize - the desired cursor size, an unsigned integer value
  10916.                          that contains both the scan start and end line. 
  10917.                          To determine this value use the following formula:
  10918.                          Size = StartLine*256+EndLine.  The start and end
  10919.                          lines for MONOCHROME monitors are from "0" to "13"
  10920.                          and for COLOR monitors from "0" to "7".
  10921.  
  10922.           Example:
  10923.  
  10924.           #include <scl1.h>
  10925.           #include <scl1clor.h>
  10926.  
  10927.           main()
  10928.           {
  10929.           int topline,bottomline;
  10930.  
  10931.           InitVideo();
  10932.           topline=0;
  10933.  
  10934.           if(Video()==COLOR)
  10935.              bottomline=7;
  10936.           else
  10937.              bottomline=13;
  10938.           printf("\nYour cursor will start growing: ");
  10939.           for(topline=bottomline-1;topline > 0;--topline)
  10940.              {
  10941.              SetCurSize(topline * 256 + bottomline);
  10942.              WaitTime(50);
  10943.              }
  10944.  
  10945.           printf("\nYour cursor will now return to normal: ");
  10946.           for(;topline < bottomline;++topline)
  10947.              {
  10948.              SetCurSize(topline * 256 + bottomline);
  10949.              WaitTime(50);
  10950.              }
  10951.           }
  10952.  
  10953.                                      Page -181-
  10954.  
  10955.  
  10956.  
  10957.  
  10958.  
  10959.                           SCL1 Version 2.0 Reference Manual
  10960.  
  10961.  
  10962.                                                              SetDialogColor
  10963.  
  10964.           Function:    SetDialogColor
  10965.  
  10966.           Purpose:     Lets you define the colors for the dialog type
  10967.                        functions.  Sets global variables D_NColor, which
  10968.                        holds the normal color attributes, D_RColor, which
  10969.                        holds the reversed color attributes and D_HColor,
  10970.                        which holds the highlight color attributes. If this
  10971.                        function is not called the variables will contain
  10972.                        the following default values; D_NColor=0x7,
  10973.                        D_RColor=0x70 and D_HColor=0x0f.
  10974.  
  10975.           Declaration: void SetDialogColor(int NColor,int RColor,
  10976.                             int HColor);
  10977.  
  10978.           Returns:     Nothing
  10979.  
  10980.           Parameters:
  10981.  
  10982.                 NColor - normal color attributes for the dialog functions
  10983.                          (integer).
  10984.  
  10985.                 RColor - reversed color attributes for the dialog functions
  10986.                          (integer).
  10987.  
  10988.                 HColor - highlight color attributes for the dialog
  10989.                          functions (integer).
  10990.  
  10991.           Example:
  10992.  
  10993.           #include <scl1.h>
  10994.           #include <scl1clor.h>
  10995.  
  10996.           int Color1=WHITE_BLUE;
  10997.           int Color2=BLUE_WHITE;
  10998.           int Color3=WHITE_BLUE+HIGHLIGHT;
  10999.  
  11000.           main()
  11001.              {
  11002.              SetDialogColor(Color1,Color2,Color3);
  11003.              .
  11004.              .
  11005.              /* Will set the color attributes for subsequent calls to
  11006.                 dialog type functions to Color1, Color3 and Color3. */
  11007.              }
  11008.  
  11009.  
  11010.  
  11011.  
  11012.                                      Page -182-
  11013.  
  11014.  
  11015.  
  11016.  
  11017.  
  11018.                           SCL1 Version 2.0 Reference Manual
  11019.  
  11020.  
  11021.                                                            SetErrorBoxColor
  11022.  
  11023.           Function:    SetErrorBoxColor
  11024.  
  11025.           Purpose:     Lets you define the color for the Error Box
  11026.                        function.
  11027.  
  11028.           Declaration: void SetErrorBoxColor(int UColor)
  11029.  
  11030.           Returns:     Nothing
  11031.  
  11032.           Parameters:
  11033.  
  11034.                 UColor - color attribute for Error Box messages (integer).
  11035.  
  11036.           Example:
  11037.  
  11038.           #include <scl1.h>
  11039.           #include <scl1clor.h>
  11040.  
  11041.           int Color1=RED_WHITE;
  11042.  
  11043.           main()
  11044.              {
  11045.              SetErrorBoxColor(Color1);
  11046.              .
  11047.              .
  11048.              /* Will set a color for subsequent calls to the Error Box
  11049.                 function to Color1. */
  11050.              }
  11051.  
  11052.           See also ErroBox.
  11053.  
  11054.  
  11055.  
  11056.  
  11057.  
  11058.  
  11059.  
  11060.  
  11061.  
  11062.  
  11063.  
  11064.  
  11065.  
  11066.  
  11067.  
  11068.  
  11069.  
  11070.  
  11071.                                      Page -183-
  11072.  
  11073.  
  11074.  
  11075.  
  11076.  
  11077.                           SCL1 Version 2.0 Reference Manual
  11078.  
  11079.  
  11080.                                                                 SetFileMode
  11081.  
  11082.           Function:    SetFileMode
  11083.  
  11084.           Purpose:     Sets a file's attributes (system, hidden, read only,
  11085.                        etc.).
  11086.  
  11087.           Declaration: int SetFileMode(char *Filename, int NewMode);
  11088.  
  11089.           Returns:     The return value is "0" if no error occurs or the
  11090.                        DOS error code if an error occurs.  (See Appendix
  11091.                        "A", FILE FUNCTIONS, for more information).
  11092.  
  11093.           Parameters: 
  11094.  
  11095.           A mask has been defined in SCL1.H (see GetFileMode): They can be
  11096.           ored to "add" several attributes.
  11097.  
  11098.           Example:
  11099.  
  11100.           #include <scl1.h>
  11101.  
  11102.           char Filename[]="FILE.1";
  11103.  
  11104.           main()
  11105.           {
  11106.           int handle;
  11107.           unsigned int FMode;
  11108.  
  11109.           if(CreateFile(Filename,&handle,F_ARCHIVE))
  11110.              exit(-1);
  11111.           if(GetFileMode(Filename,&FMode))
  11112.              exit(-1);
  11113.           PrintFMode(FMode);
  11114.           if(SetFileMode(Filename,F_READ_ONLY | F_SYSTEM | F_HIDDEN))
  11115.              exit(-1);
  11116.           if(GetFileMode(Filename,&FMode))
  11117.              exit(-1);
  11118.           PrintFMode(FMode);
  11119.           if(SetFileMode(Filename,F_ARCHIVE))
  11120.              exit(-1);
  11121.           DeleteFile(Filename);
  11122.           }
  11123.  
  11124.  
  11125.  
  11126.  
  11127.  
  11128.  
  11129.  
  11130.                                      Page -184-
  11131.  
  11132.  
  11133.  
  11134.  
  11135.  
  11136.                           SCL1 Version 2.0 Reference Manual
  11137.  
  11138.  
  11139.                                                                 SetFileMode
  11140.  
  11141.           PrintFMode(unsigned int FMode)
  11142.           {
  11143.           printf("\nFile attributtes:\n\n");
  11144.           if(FMode & F_READ_ONLY)
  11145.              printf("\tRead Only\n");
  11146.           if(FMode & F_HIDDEN)
  11147.              printf("\tHidden\n");
  11148.           if(FMode & F_SYSTEM)
  11149.              printf("\tSystem\n");
  11150.           if(FMode & F_ARCHIVE)
  11151.              printf("\tArchive\n");
  11152.           }
  11153.  
  11154.  
  11155.  
  11156.  
  11157.  
  11158.  
  11159.  
  11160.  
  11161.  
  11162.  
  11163.  
  11164.  
  11165.  
  11166.  
  11167.  
  11168.  
  11169.  
  11170.  
  11171.  
  11172.  
  11173.  
  11174.  
  11175.  
  11176.  
  11177.  
  11178.  
  11179.  
  11180.  
  11181.  
  11182.  
  11183.  
  11184.  
  11185.  
  11186.  
  11187.  
  11188.  
  11189.                                      Page -185-
  11190.  
  11191.  
  11192.  
  11193.  
  11194.  
  11195.                           SCL1 Version 2.0 Reference Manual
  11196.  
  11197.  
  11198.                                                                 SetHorLimit
  11199.  
  11200.           Function:    SetHorLimit
  11201.  
  11202.           Purpose:     Sets the minimum and maximum mouse horizontal
  11203.                        coordinates.
  11204.  
  11205.           Declaration: void SetHorLimit(int Minimum,int Maximum);
  11206.  
  11207.           Returns:     Nothing
  11208.  
  11209.           Parameters:
  11210.  
  11211.                Minimum - integer value indicating the minimum horizontal
  11212.                          coordinate.
  11213.  
  11214.                Maximum - integer value indicating the maximum horizontal
  11215.                          coordinate.
  11216.  
  11217.           Example:
  11218.  
  11219.           #include <scl1.h>
  11220.           #include <scl1clor.h>
  11221.  
  11222.           main()
  11223.           {
  11224.           InitMouse(IM_SHOW);
  11225.           if(MSE_MouseFl)
  11226.              {
  11227.              SetHorLimit(39,39);
  11228.              printf("Mouse movement has been limited to column 39, click
  11229.                     mouse to exit\n");
  11230.              while(!MSE_LPress);
  11231.              }
  11232.           else
  11233.              printf("No mouse installed\n");
  11234.           }
  11235.  
  11236.           See also SetVerLimit.
  11237.  
  11238.  
  11239.  
  11240.  
  11241.  
  11242.  
  11243.  
  11244.  
  11245.  
  11246.  
  11247.  
  11248.                                      Page -186-
  11249.  
  11250.  
  11251.  
  11252.  
  11253.  
  11254.                           SCL1 Version 2.0 Reference Manual
  11255.  
  11256.  
  11257.                                                              SetInt24Colors
  11258.  
  11259.           Function:    SetInt24Colors
  11260.  
  11261.           Purpose:     Lets you define the color for the error display box
  11262.                        used by the TrapInt24 function.
  11263.  
  11264.           Declaration: void SetInt24Colors(int NColor, int RColor);
  11265.  
  11266.           Returns:     Nothing
  11267.  
  11268.           Parameters:
  11269.  
  11270.                 NColor - normal color attribute for the TrapInt24 error
  11271.                          display (integer).
  11272.  
  11273.                 RColor - reversed color attribute for the TrapInt24 error
  11274.                          display (integer).
  11275.  
  11276.           Example:
  11277.  
  11278.           #include <scl1.h>
  11279.           #include <scl1clor.h>
  11280.  
  11281.           int Color1=WHITE_BLACK;
  11282.           int Color2=BLACK_WHITE;
  11283.  
  11284.           main()
  11285.              {
  11286.              SetInt24Colors(Color1,Color2);
  11287.              /* Will set the colors for calls to the TrapInt24 function to
  11288.                 Color1 and Color2. */
  11289.              .
  11290.              .
  11291.              }
  11292.  
  11293.  
  11294.  
  11295.  
  11296.  
  11297.  
  11298.  
  11299.  
  11300.  
  11301.  
  11302.  
  11303.  
  11304.  
  11305.  
  11306.  
  11307.                                      Page -187-
  11308.  
  11309.  
  11310.  
  11311.  
  11312.  
  11313.                           SCL1 Version 2.0 Reference Manual
  11314.  
  11315.  
  11316.                                                                 SetMouseCur
  11317.  
  11318.           Function:    SetMouseCur
  11319.  
  11320.           Purpose:     Sets mouse cursor.  Any valid character can be used
  11321.                        as the mouse cursor.
  11322.  
  11323.           Declaration: void SetMouseCur(int Character);
  11324.  
  11325.           Returns:     Nothing
  11326.  
  11327.           Parameters:
  11328.  
  11329.              Character - any valid character to be used as the mouse cursor
  11330.                          (integer).
  11331.  
  11332.           Example:
  11333.  
  11334.           #include <scl1.h>
  11335.           #include <scl1clor.h>
  11336.  
  11337.           main()
  11338.           {
  11339.           GSSBox(WHITE_BLACK,0,0,0,24,79,1,0,0);
  11340.           InitMouse(IM_SHOW);
  11341.           if(MSE_MouseFl)
  11342.              {
  11343.              SetMouseCur('*');
  11344.              WriteScreenLen(WHITE_BLACK+HIGHLIGHT,23,2,40,"Mouse cursor
  11345.                             set to '*' character");
  11346.              WaitTime(300);
  11347.              ResetMouseCur();
  11348.              WriteScreenLen(WHITE_BLACK+HIGHLIGHT,23,2,40,"Mouse cursor
  11349.                             reset to normal");
  11350.              WaitTime(300);
  11351.              }
  11352.           else
  11353.              WriteScreenLen(WHITE_BLACK+HIGHLIGHT,23,2,40,"No mouse
  11354.                             installed.");
  11355.           }
  11356.  
  11357.  
  11358.  
  11359.  
  11360.  
  11361.  
  11362.  
  11363.  
  11364.  
  11365.  
  11366.                                      Page -188-
  11367.  
  11368.  
  11369.  
  11370.  
  11371.  
  11372.                           SCL1 Version 2.0 Reference Manual
  11373.  
  11374.  
  11375.                                                                 SetMouseIsr
  11376.  
  11377.           Function:    SetMouseIsr
  11378.  
  11379.           Purpose:     Sets an Interrupt service routine that is called
  11380.                        whenever the mouse moves or any of its buttons is
  11381.                        pressed or released.
  11382.  
  11383.           Declaration: void SetMouseIsr(void);
  11384.  
  11385.           Returns:     Nothing
  11386.  
  11387.           The following variables are set according to mouse status:
  11388.  
  11389.              MSE_LPress is set to "1" when the left button is pressed.
  11390.  
  11391.              MSE_LpX and MSE_LpY are set to the X and Y position when the
  11392.              left button is pressed.
  11393.  
  11394.              MSE_LRel, MSE_LrX and MSE_LrY are set to the X and Y position
  11395.              when the left button is released.
  11396.  
  11397.              MSE_RPress is set to "1" when the right button is pressed.
  11398.  
  11399.              MSE_RpX and MSE_RpY  are set to the X and Y position when the
  11400.              right button is pressed.
  11401.  
  11402.              MSE_RRel, MSE_RrX, and MSE_RrY are set to the X and Y position
  11403.              when the right button is released.
  11404.  
  11405.              MSE_Move is set to "1" when the mouse is moved.
  11406.  
  11407.              MSE_MoveX and MSE_MoveY hold the actual X and Y mouse
  11408.              position.
  11409.  
  11410.              MSE_DoubleClick is set to "1" when you double click the left
  11411.              mouse button.
  11412.  
  11413.              MSE_MouseFl is set to "1" when the mouse driver is present.
  11414.  
  11415.              Before ending your program you must Reset the mouse using
  11416.              ResetMouse or disable the interrupt service routine using
  11417.              DisableMouseIsr or ResetMouse.
  11418.  
  11419.  
  11420.  
  11421.  
  11422.  
  11423.  
  11424.  
  11425.                                      Page -189-
  11426.  
  11427.  
  11428.  
  11429.  
  11430.  
  11431.                           SCL1 Version 2.0 Reference Manual
  11432.  
  11433.  
  11434.                                                                 SetMouseIsr
  11435.  
  11436.           Example:
  11437.  
  11438.           #include <scl1.h>
  11439.  
  11440.           main()
  11441.              {
  11442.  
  11443.              /* do we have a mouse? */
  11444.              if(CheckMouse())
  11445.                 {
  11446.                 /* Yes */
  11447.                 ResetMouse();  /* reset mouse */
  11448.                 SetMouseIsr(); /* initialize ISR */
  11449.                 ShowMouse();   /* cursor on */
  11450.                 }
  11451.              .
  11452.              .
  11453.              .
  11454.              ResetMouse();  /* reset mouse before exit */
  11455.              }
  11456.  
  11457.           See also InitMouse
  11458.  
  11459.  
  11460.  
  11461.  
  11462.  
  11463.  
  11464.  
  11465.  
  11466.  
  11467.  
  11468.  
  11469.  
  11470.  
  11471.  
  11472.  
  11473.  
  11474.  
  11475.  
  11476.  
  11477.  
  11478.  
  11479.  
  11480.  
  11481.  
  11482.  
  11483.  
  11484.                                      Page -190-
  11485.  
  11486.  
  11487.  
  11488.  
  11489.  
  11490.                           SCL1 Version 2.0 Reference Manual
  11491.  
  11492.  
  11493.                                                                 SetMousePos
  11494.  
  11495.           Function:    SetMousePos
  11496.  
  11497.           Purpose:     Sets the mouse cursor position.
  11498.  
  11499.           Declaration: void SetMousePos(int X, int Y);
  11500.  
  11501.           Returns:     Nothing
  11502.  
  11503.           Parameters:
  11504.  
  11505.                      X - integer value indicating the horizontal
  11506.                          coordinate.
  11507.  
  11508.                      Y - integer value indicating the vertical coordinate.
  11509.  
  11510.           Example:
  11511.  
  11512.           #include <scl1.h>
  11513.           #include <scl1clor.h>
  11514.  
  11515.           main()
  11516.           {
  11517.           GSSBox(WHITE_BLACK,0,0,0,24,79,1,0,0);
  11518.           InitMouse(IM_SHOW);
  11519.           if(MSE_MouseFl)
  11520.              {
  11521.              SetMousePos(1,1);
  11522.              WriteScreen(WHITE_BLACK+HIGHLIGHT,23,2,"Mouse cursor position
  11523.                         (X,Y) = 1,1");
  11524.              WaitTime(200);
  11525.              SetMousePos(39,12);
  11526.              WriteScreen(WHITE_BLACK+HIGHLIGHT,23,2,"Mouse cursor position
  11527.                         (X,Y) = 39,12");
  11528.              WaitTime(200);
  11529.              SetMousePos(78,23);
  11530.              WriteScreen(WHITE_BLACK+HIGHLIGHT,23,2,"Mouse cursor position
  11531.                         (X,Y) = 78,23");
  11532.              WaitTime(200);
  11533.              }
  11534.           else
  11535.              WriteScreen(WHITE_BLACK+HIGHLIGHT,23,2,"No mouse installed.");
  11536.           }
  11537.  
  11538.  
  11539.  
  11540.  
  11541.  
  11542.  
  11543.                                      Page -191-
  11544.  
  11545.  
  11546.  
  11547.  
  11548.  
  11549.                           SCL1 Version 2.0 Reference Manual
  11550.  
  11551.  
  11552.                                                              SetShadowColor
  11553.  
  11554.           Function:    SetShadowColor
  11555.  
  11556.           Purpose:     Sets the shadow color for subsequent shadow effects
  11557.                        drawn.  When calling functions that support a shadow
  11558.                        effect, this function will permit you to select the
  11559.                        color to be XOR'ed with the background color to
  11560.                        produce a pleasing effect.  You must specify the
  11561.                        color in these functions as "0".  If you prefer a
  11562.                        solid color for the shadow effect you should specify
  11563.                        it as a color parameter when calling the function.
  11564.  
  11565.           Declaration: void SetShadowColor(int Color);
  11566.  
  11567.           Returns:     Nothing
  11568.  
  11569.           Parameters:
  11570.  
  11571.                  Color - color attribute for the shadow effect (to be
  11572.                          XOR'ed with the background color) (integer).
  11573.  
  11574.           Example:
  11575.  
  11576.           #include <scl1.h>
  11577.           #include <scl1clor.h>
  11578.  
  11579.           main()
  11580.           {
  11581.           FillBlock(WHITE_BLACK+HIGHLIGHT,0,0,24,79,'X');
  11582.           GSSBox(WHITE_BLACK+HIGHLIGHT,0,5,20,20,60,1,0,0);
  11583.           SetShadowColor(BLACK_WHITE);
  11584.           Shadow(0,5,20,20,60);
  11585.           GetKey();
  11586.           SetShadowColor(WHITE_BLACK);
  11587.           Shadow(0,5,20,20,60);
  11588.           GetKey();
  11589.           SetShadowColor(BLACK_BLACK+HIGHLIGHT);
  11590.           Shadow(0,5,20,20,60);
  11591.           }
  11592.  
  11593.  
  11594.  
  11595.  
  11596.  
  11597.  
  11598.  
  11599.  
  11600.  
  11601.  
  11602.                                      Page -192-
  11603.  
  11604.  
  11605.  
  11606.  
  11607.  
  11608.                           SCL1 Version 2.0 Reference Manual
  11609.  
  11610.  
  11611.                                                                  SetUserBox
  11612.  
  11613.           Function:    SetUserBox
  11614.  
  11615.           Purpose:     Lets you define a different frame type than those
  11616.                        available for the Box and GSSBox functions.
  11617.  
  11618.           Declaration: void SetUserBox(int UpperLeft,int UpperRight,
  11619.                             int LowerLeft,int LowerRight,int UpperSide,
  11620.                             int BottomSide,int LeftSide,int RightSide);
  11621.  
  11622.           Returns:     Nothing
  11623.  
  11624.           Parameters:
  11625.  
  11626.              UpperLeft - upper left corner character of the box frame
  11627.                          (integer).
  11628.  
  11629.             UpperRight - upper right corner character of the box frame
  11630.                          (integer).
  11631.  
  11632.              LowerLeft - lower left corner character of the box frame
  11633.                          (integer).
  11634.  
  11635.             LowerRight - lower right corner character of the box frame
  11636.                          (integer).
  11637.  
  11638.              UpperSide - characters to be used for drawing the upper border
  11639.                          of the box frame (integer).
  11640.  
  11641.             BottomSide - characters to be used for drawing the bottom
  11642.                          border of the box frame (integer).
  11643.  
  11644.               LeftSide - characters to be used for drawing the left border
  11645.                          of the box frame (integer).
  11646.  
  11647.              RightSide - characters to be used for drawing the right border
  11648.                          of the box frame (integer).
  11649.  
  11650.  
  11651.  
  11652.  
  11653.  
  11654.  
  11655.  
  11656.  
  11657.  
  11658.  
  11659.  
  11660.  
  11661.                                      Page -193-
  11662.  
  11663.  
  11664.  
  11665.  
  11666.  
  11667.                           SCL1 Version 2.0 Reference Manual
  11668.  
  11669.  
  11670.                                                                  SetUserBox
  11671.  
  11672.           Example:
  11673.  
  11674.           #include <scl1.h>
  11675.           #include <scl1clor.h>
  11676.  
  11677.           main()
  11678.           {
  11679.           SetUserBox(21,21,21,21,21,21,21,21);
  11680.           GSSBox(BLACK_WHITE,12,2,2,22,77,1,0,0);
  11681.           }
  11682.  
  11683.  
  11684.  
  11685.  
  11686.  
  11687.  
  11688.  
  11689.  
  11690.  
  11691.  
  11692.  
  11693.  
  11694.  
  11695.  
  11696.  
  11697.  
  11698.  
  11699.  
  11700.  
  11701.  
  11702.  
  11703.  
  11704.  
  11705.  
  11706.  
  11707.  
  11708.  
  11709.  
  11710.  
  11711.  
  11712.  
  11713.  
  11714.  
  11715.  
  11716.  
  11717.  
  11718.  
  11719.  
  11720.                                      Page -194-
  11721.  
  11722.  
  11723.  
  11724.  
  11725.  
  11726.                           SCL1 Version 2.0 Reference Manual
  11727.  
  11728.  
  11729.                                                              SetUserBoxLine
  11730.  
  11731.           Function:    SetUserBoxLine
  11732.  
  11733.           Purpose:     Lets you define a line type for drawing lines inside
  11734.                        boxes that use lines defined by using the SetUserBox
  11735.                        function.
  11736.  
  11737.           Declaration: void SetUserBoxLine(int HLeft,int HRight,
  11738.                             int VUpper,int VLower);
  11739.  
  11740.           Returns:     Nothing
  11741.  
  11742.           Parameters:
  11743.  
  11744.                  HLeft - horizontal left terminating character of the line
  11745.                          (integer).
  11746.  
  11747.                 HRight - horizontal right terminating character of the line
  11748.                          (integer).
  11749.  
  11750.                 VUpper - vertical upper terminating character of the line
  11751.                          (integer).
  11752.  
  11753.                 VLower - vertical lower terminating character of the line
  11754.                          (integer).
  11755.  
  11756.           Example:
  11757.  
  11758.           #include (scl1.h>
  11759.  
  11760.           main()
  11761.              {
  11762.              SetUserBoxLine(201,188,200,189,205,205,186,186);
  11763.              .
  11764.              .
  11765.              /* Will set a user type frame to double line, exactly as
  11766.               defined in standard frame type 0 of the Box and GSSBox
  11767.               functions*/
  11768.              }
  11769.  
  11770.  
  11771.  
  11772.  
  11773.  
  11774.  
  11775.  
  11776.  
  11777.  
  11778.  
  11779.                                      Page -195-
  11780.  
  11781.  
  11782.  
  11783.  
  11784.  
  11785.                           SCL1 Version 2.0 Reference Manual
  11786.  
  11787.  
  11788.                                                                 SetVerLimit
  11789.  
  11790.           Function:    SetVerLimit
  11791.  
  11792.           Purpose:     Sets the mouse minimum and maximum vertical
  11793.                        coordinates.
  11794.  
  11795.           Declaration: void SetVerLimit(int Minimum,int Maximum);
  11796.  
  11797.           Returns:     Nothing
  11798.  
  11799.           Parameters:
  11800.  
  11801.                Minimum - integer value indicating the minimum vertical
  11802.                          coordinate.
  11803.  
  11804.                Maximum - integer value indicating the maximum vertical
  11805.                          coordinate.
  11806.           Example:
  11807.  
  11808.           #include <scl1.h>
  11809.           #include <scl1clor.h>
  11810.  
  11811.           main()
  11812.           {
  11813.           InitMouse(IM_SHOW);
  11814.           if(MSE_MouseFl)
  11815.              {
  11816.              SetVerLimit(11,11);
  11817.              printf("Mouse movement has been limited to line 11, click
  11818.                     mouse to exit\n");
  11819.              while(!MSE_LPress);
  11820.              }
  11821.           else
  11822.              printf("No mouse installed\n");
  11823.           }
  11824.  
  11825.           See also SetHorLimit.
  11826.  
  11827.  
  11828.  
  11829.  
  11830.  
  11831.  
  11832.  
  11833.  
  11834.  
  11835.  
  11836.  
  11837.  
  11838.                                      Page -196-
  11839.  
  11840.  
  11841.  
  11842.  
  11843.  
  11844.                           SCL1 Version 2.0 Reference Manual
  11845.  
  11846.  
  11847.                                                                SetVideoMode
  11848.  
  11849.           Function:    SetVideoMode
  11850.  
  11851.           Purpose:     Sets the desired video mode.  See the BIOS reference
  11852.                        manual for the available video modes. SCL1 only
  11853.                        supports the 40 and 80 column text modes.
  11854.  
  11855.           Declaration: void SetVideoMode(int NewMode);
  11856.  
  11857.           Returns:     Nothing
  11858.  
  11859.           Parameters:
  11860.  
  11861.                NewMode - video mode as defined by the DOS (integer).
  11862.  
  11863.           Example:
  11864.  
  11865.           #include <scl1.h>
  11866.  
  11867.           /* Initializes Video mode to mode 3 in case of color, EGA or VGA
  11868.              or to mode 7 in case mono */
  11869.  
  11870.           void InitVideo(void)
  11871.           {
  11872.  
  11873.           Video();
  11874.           if(VC_Segment==COLOR)
  11875.              SetVideoMode(3);
  11876.           else
  11877.              SetVideoMode(7);
  11878.           }
  11879.  
  11880.  
  11881.  
  11882.  
  11883.  
  11884.  
  11885.  
  11886.  
  11887.  
  11888.  
  11889.  
  11890.  
  11891.  
  11892.  
  11893.  
  11894.  
  11895.  
  11896.  
  11897.                                      Page -197-
  11898.  
  11899.  
  11900.  
  11901.  
  11902.  
  11903.                           SCL1 Version 2.0 Reference Manual
  11904.  
  11905.  
  11906.                                                                SetVideoPage
  11907.  
  11908.           Function:    SetVideoPage
  11909.  
  11910.           Purpose:     Sets the active video page.  See the BIOS reference
  11911.                        manual for the available video pages.
  11912.  
  11913.           Declaration: void SetVideoPage(int NewPage);
  11914.  
  11915.           Returns:     Nothing
  11916.  
  11917.           Parameters:
  11918.  
  11919.                NewPage - video page (supported by your display adapter) as
  11920.                          defined in the BIOS (integer).
  11921.  
  11922.           Example:
  11923.  
  11924.           #include <scl1.h>
  11925.           #include <scl1clor.h>
  11926.  
  11927.           main()
  11928.           {
  11929.           Video();
  11930.           if(VC_Monitor==VC_MDA)
  11931.              {
  11932.              printf("Monochrome monitors do not support video pages\n");
  11933.              exit(-1);
  11934.              }
  11935.           Cls(WHITE_BLACK,CLS_ALL);
  11936.           WriteScreen(WHITE_BLACK,10,35,"Video page 0");
  11937.           WaitTime(100);
  11938.           SetVideoPage(1);
  11939.           Cls(BLACK_WHITE,CLS_ALL);
  11940.           WriteScreen(BLACK_WHITE,10,35,"Video page 1");
  11941.           WaitTime(100);
  11942.           SetVideoPage(0);
  11943.           WaitTime(100);
  11944.           SetVideoPage(1);
  11945.           WaitTime(100);
  11946.           SetVideoPage(0);
  11947.           }
  11948.  
  11949.  
  11950.  
  11951.  
  11952.  
  11953.  
  11954.  
  11955.  
  11956.                                      Page -198-
  11957.  
  11958.  
  11959.  
  11960.  
  11961.  
  11962.                           SCL1 Version 2.0 Reference Manual
  11963.  
  11964.  
  11965.                                                                SetVideo4350
  11966.                                                                  Setvideo25
  11967.  
  11968.           Function:    SetVideo4350
  11969.                        SetVideo25
  11970.  
  11971.           Purpose:     The SetVideo4350 function sets the display mode to
  11972.                        43 lines (EGA display adapters) or to the 50 lines
  11973.                        (VGA display adapters).  The SetVideo25 function
  11974.                        resets the display mode to 25 lines.
  11975.  
  11976.           Declaration: void SetVideo4350(void);
  11977.                        void SetVideo25();
  11978.  
  11979.           Returns:     Nothing
  11980.  
  11981.           Parameters:  None
  11982.  
  11983.           Example:
  11984.  
  11985.           #include <scl1.h>
  11986.           #include <scl1clor.h>
  11987.  
  11988.           main()
  11989.           {
  11990.           Video();
  11991.           if(VC_Monitor != VC_VGA && VC_Monitor != VC_EGA)
  11992.              {
  11993.              printf("Video system does not supports 43/50 lines video
  11994.                     mode\n");
  11995.              exit(-1);
  11996.              }
  11997.           SetVideo4350();
  11998.           FillBlock(WHITE_BLACK,0,0,VC_Lines-1,79,'*');
  11999.           MessageOn(BLACK_WHITE,"43/50 lines Video Mode\n
  12000.                    press any key...");
  12001.           GetKey();
  12002.  
  12003.           SetVideo25();
  12004.           FillBlock(WHITE_BLACK,0,0,VC_Lines-1,79,'*');
  12005.           MessageOn(BLACK_WHITE,"25 lines Video Mode\npress any key...");
  12006.           GetKey();
  12007.  
  12008.           Cls(7,CLS_ALL);
  12009.           }
  12010.  
  12011.  
  12012.  
  12013.  
  12014.  
  12015.                                      Page -199-
  12016.  
  12017.  
  12018.  
  12019.  
  12020.  
  12021.                           SCL1 Version 2.0 Reference Manual
  12022.  
  12023.  
  12024.                                                                      Shadow
  12025.  
  12026.           Function:    Shadow
  12027.  
  12028.           Purpose:     Draws a shadow to a screen area.
  12029.  
  12030.           Declaration: void Shadow(int Color,int UpperRow, int LeftCol,
  12031.                             int LowerRow, int RightCol);
  12032.  
  12033.           Returns:     Nothing
  12034.  
  12035.           Parameters:
  12036.  
  12037.                  Color - color attribute of the desired shadow effect. If a
  12038.                          value of "0" is specified the shadow effect is
  12039.                          XOR'ed. to the screen area.  You can use the
  12040.                          SetShadowColor function to specify the color to be
  12041.                          XOR'ed with the foreground (integer).
  12042.  
  12043.               UpperRow - upper row coordinate of the area (integer).
  12044.  
  12045.                LeftCol - left column coordinate of the area (integer).
  12046.  
  12047.               LowerRow - lower row coordinate of the area (integer).
  12048.  
  12049.               RightCol - right column coordinate of the area (integer).
  12050.  
  12051.           Example:
  12052.  
  12053.           #include <scl1.h>
  12054.           #include <scl1clor.h>
  12055.  
  12056.           main()
  12057.           {
  12058.           Box(WHITE_BLACK,0,10,10,20,70);
  12059.           Shadow(BLACK_WHITE,10,10,20,70);
  12060.           }
  12061.  
  12062.  
  12063.  
  12064.  
  12065.  
  12066.  
  12067.  
  12068.  
  12069.  
  12070.  
  12071.  
  12072.  
  12073.  
  12074.                                      Page -200-
  12075.  
  12076.  
  12077.  
  12078.  
  12079.  
  12080.                           SCL1 Version 2.0 Reference Manual
  12081.  
  12082.  
  12083.                                                                   ShowMouse
  12084.  
  12085.           Function:    ShowMouse
  12086.  
  12087.           Purpose:     Makes mouse cursor visible.
  12088.  
  12089.           Declaration: void ShowMouse(void);
  12090.  
  12091.           Returns:     Nothing
  12092.  
  12093.           Parameters:  None
  12094.  
  12095.           Example:
  12096.  
  12097.           #include <scl1.h>
  12098.  
  12099.           main()
  12100.              {
  12101.              InitMouse(IM_SHOW); /* initialize mouse, turn cursor on */
  12102.  
  12103.              if(MSE_MouseFl)
  12104.                 {
  12105.                 printf("We have a mouse, click the left button to turn
  12106.                         mouse cursor off.\n");
  12107.                 WaitKeyMouse();
  12108.                 HideMouse();
  12109.                 printf("Click again to turn mouse cursor on.\n");
  12110.                 WaitKeyMouse();
  12111.                 ShowMouse();
  12112.                 printf("Click to exit.\n");
  12113.                 WaitKeyMouse();
  12114.                 }
  12115.              else
  12116.                 printf("We don't have a mouse\n");
  12117.              }
  12118.  
  12119.  
  12120.  
  12121.  
  12122.  
  12123.  
  12124.  
  12125.  
  12126.  
  12127.  
  12128.  
  12129.  
  12130.  
  12131.  
  12132.  
  12133.                                      Page -201-
  12134.  
  12135.  
  12136.  
  12137.  
  12138.  
  12139.                           SCL1 Version 2.0 Reference Manual
  12140.  
  12141.  
  12142.                                                                SortPointers
  12143.  
  12144.           Function:    SortPointers
  12145.  
  12146.           Purpose:     Sorts a null terminated array of char pointers that
  12147.                        hold the address of strings according in
  12148.                        alphabetical order.
  12149.  
  12150.           Declaration: void SortPointers(char *p[]);
  12151.  
  12152.           Returns:     Nothing
  12153.  
  12154.           Parameters:
  12155.  
  12156.                    p - pointer to a null terminated array of char pointers.
  12157.  
  12158.           Example:
  12159.  
  12160.           #include <scl1.h>
  12161.  
  12162.           char *names[]={
  12163.              "Mozart",
  12164.              "Villa-Lobos",
  12165.              "Chopin",
  12166.              "Bach",
  12167.              "Schubert",
  12168.              "Debussy",
  12169.              "Albeniz",
  12170.              "Beethoven",
  12171.              "Falla",
  12172.              0,
  12173.              };
  12174.  
  12175.           main()
  12176.           {
  12177.           int i;
  12178.  
  12179.           SortPointers(names);
  12180.           for(i=0;names[i];++i)
  12181.              printf("%s\n",names[i]);
  12182.           }
  12183.  
  12184.  
  12185.  
  12186.  
  12187.  
  12188.  
  12189.  
  12190.  
  12191.  
  12192.                                      Page -202-
  12193.  
  12194.  
  12195.  
  12196.  
  12197.  
  12198.                           SCL1 Version 2.0 Reference Manual
  12199.  
  12200.  
  12201.                                                                       Sound
  12202.  
  12203.           Function:    Sound
  12204.  
  12205.           Purpose:     Sets a sound frequency.
  12206.  
  12207.           Declaration: void Sound(int Freq);
  12208.  
  12209.           Returns:     Nothing
  12210.  
  12211.           Parameters:
  12212.  
  12213.                 Freq - the desired frequency in hertz (integer).
  12214.  
  12215.           Example:
  12216.  
  12217.           #include <scl1.h>
  12218.  
  12219.           main()
  12220.              {
  12221.              SoundOn();
  12222.              for(Freq=400;Freq<2000;Freq+=100)
  12223.                 {
  12224.                 Sound(Freq);
  12225.                 WaitTime(10);
  12226.                 }
  12227.              SoundOff();
  12228.              }
  12229.  
  12230.           See the note definitions in header file SCL1SND.H.
  12231.  
  12232.  
  12233.  
  12234.  
  12235.  
  12236.  
  12237.  
  12238.  
  12239.  
  12240.  
  12241.  
  12242.  
  12243.  
  12244.  
  12245.  
  12246.  
  12247.  
  12248.  
  12249.  
  12250.  
  12251.                                      Page -203-
  12252.  
  12253.  
  12254.  
  12255.  
  12256.  
  12257.                           SCL1 Version 2.0 Reference Manual
  12258.  
  12259.  
  12260.                                                                    SoundOff
  12261.                                                                     SoundOn
  12262.  
  12263.           Function:    SoundOff
  12264.                        SoundOn
  12265.  
  12266.  
  12267.           Purpose:     Turns the speaker Off or On.
  12268.  
  12269.  
  12270.           Declaration: void SoundOff(void);
  12271.                        void SoundOn(void);
  12272.  
  12273.           Returns:     Nothing
  12274.  
  12275.           Parameters:  None
  12276.  
  12277.           Example:
  12278.  
  12279.           #include <scl1.h>
  12280.  
  12281.           main()
  12282.              {
  12283.              SoundOn();
  12284.              for(Freq=400;Freq<2000;Freq+=100)
  12285.                 {
  12286.                 Sound(Freq);
  12287.                 WaitTime(10);
  12288.                 }
  12289.              SoundOff();
  12290.              }
  12291.  
  12292.           See the note definitions in header file SCL1SND.H.
  12293.  
  12294.  
  12295.  
  12296.  
  12297.  
  12298.  
  12299.  
  12300.  
  12301.  
  12302.  
  12303.  
  12304.  
  12305.  
  12306.  
  12307.  
  12308.  
  12309.  
  12310.                                      Page -204-
  12311.  
  12312.  
  12313.  
  12314.  
  12315.  
  12316.                           SCL1 Version 2.0 Reference Manual
  12317.  
  12318.  
  12319.                                                                   StopWatch
  12320.  
  12321.           Function:    StopWatch
  12322.  
  12323.           Purpose:     Measures elapsed time in 1/100 seconds
  12324.  
  12325.           Declaration: long StopWatch(int Function);
  12326.  
  12327.           Returns:     Elapsed Time between calls to the function.  The
  12328.                        stop watch is started by calling the function with
  12329.                        the SW_START parameter.  When the stop watch is
  12330.                        stopped by calling the function with the SW_STOP
  12331.                        parameter it returns the elapsed time.
  12332.  
  12333.           Parameters:
  12334.  
  12335.                    See the above explanation.
  12336.  
  12337.           Example:
  12338.  
  12339.           #include <scl1.h>
  12340.  
  12341.           main()
  12342.           {
  12343.           unsigned int i;
  12344.           register unsigned int j;
  12345.           long t;
  12346.  
  12347.           StopWatch(SW_START);
  12348.           for(i=0;i < 65535;++i);
  12349.           t=StopWatch(SW_STOP);
  12350.           printf("Your computer needs %li/100 of a second to count from
  12351.                     1 to 65535.\n",t);
  12352.  
  12353.           StopWatch(SW_START);
  12354.           for(j=0;j < 65535;++j);
  12355.           t=StopWatch(SW_STOP);
  12356.           printf("This time can be reduced to %li/100 of a second by using
  12357.                    a register variable.\n",t);
  12358.           }
  12359.  
  12360.  
  12361.  
  12362.  
  12363.  
  12364.  
  12365.  
  12366.  
  12367.  
  12368.  
  12369.                                      Page -205-
  12370.  
  12371.  
  12372.  
  12373.  
  12374.  
  12375.                           SCL1 Version 2.0 Reference Manual
  12376.  
  12377.  
  12378.                                                                     TagItem
  12379.  
  12380.           Function:    TagItem
  12381.  
  12382.           Purpose:     Will permit the display of one item and permits the
  12383.                        user to tag or untag it.  To tag or untag an item,
  12384.                        move the cursor to the tag indicator (a pair of
  12385.                        parenthesis) and press the SPACEBAR.  An item can
  12386.                        also be tagged or untagged by clicking the left
  12387.                        mouse button after pointing it.  An item that has
  12388.                        been tagged will be displayed with a check mark (√)
  12389.                        between the tag indicating parenthesis.  This is a
  12390.                        dialog type function that can either be used alone
  12391.                        or as one of the field types for the fields option.
  12392.  
  12393.           Declaration: int TagItem(int Message, TIData *tg)
  12394.  
  12395.           Returns:     This is a dialog type function. See Appendix "E" for
  12396.                        a description of the general operation of these
  12397.                        functions.  The return value is a message described
  12398.                        in the Messages section.
  12399.  
  12400.           Parameters:
  12401.  
  12402.           The TagItem parameters must be passed to a structure of the type
  12403.           SData1 as follows.
  12404.  
  12405.           Structure type TIData.
  12406.  
  12407.           typedef struct{
  12408.              int Color;
  12409.              int Row;
  12410.              int Col;
  12411.              int TagFl;
  12412.              char *String;
  12413.              unsigned int *ExitKeys;
  12414.              unsigned int EventInfo;
  12415.              }TIData;
  12416.  
  12417.           where,
  12418.  
  12419.                  Color - color attributes for the display of the TagItem
  12420.                          (integer).
  12421.  
  12422.                    Row - row position where the TagItem is displayed
  12423.                          (integer).
  12424.  
  12425.                    Col - column position where the TagItem is displayed
  12426.                          (integer).
  12427.  
  12428.                                      Page -206-
  12429.  
  12430.  
  12431.  
  12432.  
  12433.  
  12434.                           SCL1 Version 2.0 Reference Manual
  12435.  
  12436.  
  12437.                                                                     TagItem
  12438.  
  12439.                 String - char pointer to the text used to identify the
  12440.                          TagItem.
  12441.  
  12442.                  TagFl - a flag that will have a value of "1" if the item
  12443.                          has been tagged and a value of "0" if it has not
  12444.                          been tagged (integer).
  12445.  
  12446.               ExitKeys - array of keys defined as exit keys (unsigned
  12447.                          integer).
  12448.  
  12449.              EventInfo - this structure element will hold the last key
  12450.                          pressed (unsigned integer).
  12451.  
  12452.           Messages:
  12453.  
  12454.           The following messages can be sent to Select:
  12455.  
  12456.                          TI_INIT -   initialize the TIData structure to
  12457.                                      NULL and set the following default
  12458.                                      values:
  12459.  
  12460.                              Color - set to white characters in a black
  12461.                                      background or the normal color defined
  12462.                                      by calling SetDialogColors.
  12463.  
  12464.                         TI_DRAW - display the Tag Item with the current
  12465.                                   information.
  12466.  
  12467.                       TI_ACTIVE - take control to tag an item.
  12468.  
  12469.                  TI_CHECK_MOUSE - check if the mouse has been clicked after
  12470.                                   pointing to the area defined by the
  12471.                                   function.
  12472.  
  12473.                        TI_RESET - when this message is sent the position
  12474.                                   variables are reset to the default value. 
  12475.                                   If the exit keys have not been defined
  12476.                                   they are set to the default exit keys.
  12477.  
  12478.           The following messages can be returned by TagItem:
  12479.  
  12480.                           TI_OK - the requested action has been performed.
  12481.  
  12482.                     TI_EXIT_KEY - a defined exit key has been pressed.
  12483.  
  12484.  
  12485.  
  12486.  
  12487.                                      Page -207-
  12488.  
  12489.  
  12490.  
  12491.  
  12492.  
  12493.                           SCL1 Version 2.0 Reference Manual
  12494.  
  12495.  
  12496.                                                                     TagItem
  12497.  
  12498.                  TI_MOUSE_EVENT - the mouse has been clicked but it has not
  12499.                                   been pointed to the area defined by the
  12500.                                   function.
  12501.  
  12502.                  TI_ILLEGAL_KEY - an undefined key has been pressed.
  12503.  
  12504.                     TI_MY_MOUSE - the mouse has been clicked after pointing
  12505.                                   to the area defined by the function. This
  12506.                                   message is in response to a
  12507.                                   TI_CHECK_MOUSE message.
  12508.  
  12509.           Example:
  12510.  
  12511.           #include <scl1.h>
  12512.           #include <scl1keys.h>
  12513.           #include <scl1clor.h>
  12514.  
  12515.           TIData ti={WHITE_BLACK,12,28,0,"Create Backup files",0,0};
  12516.  
  12517.           main()
  12518.           {
  12519.           int Mess;
  12520.  
  12521.           Cls(WHITE_BLACK,0,0,24,79);
  12522.           TagItem(TI_RESET,&ti);
  12523.           TagItem(TI_DRAW,&ti);
  12524.           do
  12525.              {
  12526.              Mess=TagItem(TI_ACTIVE,&ti);
  12527.              }while(Mess != TI_EXIT_KEY);
  12528.           }
  12529.  
  12530.  
  12531.  
  12532.  
  12533.  
  12534.  
  12535.  
  12536.  
  12537.  
  12538.  
  12539.  
  12540.  
  12541.  
  12542.  
  12543.  
  12544.  
  12545.  
  12546.                                      Page -208-
  12547.  
  12548.  
  12549.  
  12550.  
  12551.  
  12552.                           SCL1 Version 2.0 Reference Manual
  12553.  
  12554.  
  12555.                                                                     TagList
  12556.  
  12557.           Function:    TagList
  12558.  
  12559.           Purpose:     Displays in a ScrollBox any number of items that the
  12560.                        user can tag using the keyboard (spacebar) or the
  12561.                        mouse.
  12562.  
  12563.           Declaration: int TagList(int NColor, int RColor,struct
  12564.                            TagList *tl);
  12565.  
  12566.           Returns:     Return value is a number above "0" if the user
  12567.                        pressed ENTER to exit, otherwise returns "-1".  In
  12568.                        case the user has pressed ESCAPE to exit the tagged
  12569.                        items are returned in the same way as they were
  12570.                        received.
  12571.  
  12572.           Parameters:
  12573.  
  12574.           The taglist information must be given as an array of structures
  12575.           as follows:
  12576.  
  12577.              struct TagList{
  12578.                 char TagFl;
  12579.                 char *String;
  12580.                 };
  12581.  
  12582.           where,
  12583.  
  12584.                  TagFl - equals "1" if item is tagged (char).
  12585.  
  12586.                 String - a pointer to the item string (char).
  12587.  
  12588.           Note: The TagList structure must be zero terminated.
  12589.  
  12590.           The function is called with the following parameters:
  12591.  
  12592.                 NColor - color used for box and items (integer).
  12593.  
  12594.                 RColor - color used for selected item (integer).
  12595.  
  12596.                     tl - pointer to structure TagList. This structure is
  12597.                          defined in SCL1.H:
  12598.  
  12599.  
  12600.  
  12601.  
  12602.  
  12603.  
  12604.  
  12605.                                      Page -209-
  12606.  
  12607.  
  12608.  
  12609.  
  12610.  
  12611.                           SCL1 Version 2.0 Reference Manual
  12612.  
  12613.  
  12614.                                                                     TagList
  12615.  
  12616.           Example:
  12617.  
  12618.           #include <scl1.h>
  12619.           #include <scl1clor.h>
  12620.  
  12621.           struct TagList tl[]={
  12622.              0,"Option 1",
  12623.              0,"Option 2",
  12624.              0,"Option 3",
  12625.              0,"Option 4",
  12626.              0,"Option 5",
  12627.              0,"Option 6",
  12628.              0,"Option 7",
  12629.              0,"Option 8",
  12630.              0,"Option 9",
  12631.              0};
  12632.  
  12633.           main()
  12634.           {
  12635.           int i;
  12636.  
  12637.           if(TagList(WHITE_BLACK,BLACK_WHITE,tl) != -1) 
  12638.                 /* cancel selected?  */
  12639.              {
  12640.              printf("\nThe following options were tagged:\n");
  12641.              for(i=0;i < 9;++i)
  12642.                 {
  12643.                 if(tl[i].TagFl)
  12644.                    printf("%s\n",tl[i].String);
  12645.                 }
  12646.              }
  12647.           else
  12648.              printf("\nOperation canceled by user\n");
  12649.           }
  12650.  
  12651.           NOTE: The new dialog type function TagList2 provides an
  12652.                 alternative way to accomplish this task.
  12653.  
  12654.  
  12655.  
  12656.  
  12657.  
  12658.  
  12659.  
  12660.  
  12661.  
  12662.  
  12663.  
  12664.                                      Page -210-
  12665.  
  12666.  
  12667.  
  12668.  
  12669.  
  12670.                           SCL1 Version 2.0 Reference Manual
  12671.  
  12672.  
  12673.                                                                    Taglist2
  12674.  
  12675.           Function:    TagList2
  12676.  
  12677.           Purpose:     Displays a list of items and permits tagging and
  12678.                        untagging of selected items.  The list will scroll
  12679.                        vertically when the number of items is larger than
  12680.                        the display length using the cursor keys or the
  12681.                        mouse. Pressing the SPACEBAR key or clicking the
  12682.                        mouse in a highlighted item tags the desired item.
  12683.  
  12684.           Declaration: int Taglist2(int Message,TLData *p,...)
  12685.  
  12686.           Returns:     This is a dialog derived function. See Appendix "E"
  12687.                        for a description of the general operation  of these
  12688.                        functions.  The return value is a message described
  12689.                        in the Messages section.
  12690.  
  12691.           Parameters:
  12692.  
  12693.           The Tag List information must be given in a structure defined as
  12694.           type TLData. The structure elements are as follows:
  12695.  
  12696.           typedef struct{
  12697.              int NColor;
  12698.              int RColor;
  12699.              int TColor;
  12700.              int UpperRow;
  12701.              int LeftCol;
  12702.              int LowerRow;
  12703.              int RightCol;
  12704.              char **Array;
  12705.              char *TagArray;
  12706.              }TLData;
  12707.  
  12708.           where,
  12709.  
  12710.                 NColor - color attribute for normal display (integer).
  12711.  
  12712.                 RColor - color attributes for reversed display (integer).
  12713.  
  12714.                 TColor - color attributes to be used for displaying a
  12715.                          tagged item (integer).
  12716.  
  12717.               UpperRow - upper row coordinate of the window (integer).
  12718.  
  12719.                LeftCol - left column coordinate of the window (integer).
  12720.  
  12721.  
  12722.  
  12723.                                      Page -211-
  12724.  
  12725.  
  12726.  
  12727.  
  12728.  
  12729.                           SCL1 Version 2.0 Reference Manual
  12730.  
  12731.  
  12732.                                                                    Taglist2
  12733.  
  12734.               LowerRow - lower row coordinate of the window (integer).
  12735.  
  12736.               RightCol - right column coordinate of the window (integer).
  12737.  
  12738.                  Array - pointer to array of pointers to be displayed.
  12739.  
  12740.               TagArray - a char pointer to an array that hold the tagging
  12741.                          information about each item.
  12742.  
  12743.           The messages that can be sent to the TagList2 function are:
  12744.  
  12745.                         TL_INIT - initialize the TLData structure as
  12746.                                   follows:
  12747.  
  12748.                             NColor - set to white characters in a black
  12749.                                      background or the normal color defined
  12750.                                      by calling SetDialogColors.
  12751.  
  12752.                             RColor - set to highlighted white characters in
  12753.                                      a black background or the normal color
  12754.                                      defined by calling SetDialogColors.
  12755.  
  12756.                             TColor - set to black characters in a white
  12757.                                      background or the reversed color
  12758.                                      defined by calling SetDialogColors.
  12759.  
  12760.                           UpperRow - set to row "6".
  12761.  
  12762.                            LeftCol - set to column "5" for 40 column
  12763.                                      display and "34" for 80 column
  12764.                                      display.
  12765.  
  12766.                           LowerRow - set to row "17" for 24 row display and
  12767.                                      "29" for 43 row display.
  12768.  
  12769.                           RightCol - set to row "34" for 40 column display
  12770.                                      and "55" for 80 column display.
  12771.  
  12772.                         TL_DRAW - display the Tag List with the current
  12773.                                   information.
  12774.  
  12775.  
  12776.  
  12777.  
  12778.  
  12779.  
  12780.  
  12781.  
  12782.                                      Page -212-
  12783.  
  12784.  
  12785.  
  12786.  
  12787.  
  12788.                           SCL1 Version 2.0 Reference Manual
  12789.  
  12790.  
  12791.                                                                    Taglist2
  12792.  
  12793.                       TL_ACTIVE - browse through the displayed items and
  12794.                                   permit the selection or tagging of them
  12795.                                   using the cursor movement keys as
  12796.                                   follows:
  12797.  
  12798.                          Key                      action
  12799.  
  12800.                        Up Arrow         cursor one item up.
  12801.                        Down Arrow       cursor one item down.
  12802.                        END              cursor to end of file list.
  12803.                        HOME             cursor to beginning of list.
  12804.                        Page Up          cursor one screen up.
  12805.                        Page Down        cursor one screen down.
  12806.                        SpaceBar         Tag or Untag an item
  12807.  
  12808.           The messages that TagList2 can return are:
  12809.  
  12810.                        TL_OK - the requested action has been performed.
  12811.  
  12812.                    TL_CANCEL - cancel the TagList2 operation.
  12813.  
  12814.           Example:
  12815.  
  12816.           #include <scl1.h>
  12817.  
  12818.           char *options[]={
  12819.              "Option 1",
  12820.              "Option 2",
  12821.              "Option 3",
  12822.              "Option 4",
  12823.              "Option 5",
  12824.              "Option 6",
  12825.              "Option 7",
  12826.              0};
  12827.  
  12828.           char tarray[7];
  12829.  
  12830.           main()
  12831.           {
  12832.           TLData tl;
  12833.           int i,Mess;
  12834.  
  12835.  
  12836.  
  12837.  
  12838.  
  12839.  
  12840.  
  12841.                                      Page -213-
  12842.  
  12843.  
  12844.  
  12845.  
  12846.  
  12847.                           SCL1 Version 2.0 Reference Manual
  12848.  
  12849.  
  12850.                                                                    Taglist2
  12851.  
  12852.           TagList2(TL_INIT,&tl);        /* initialize structure */
  12853.           tl.UpperRow=6;                /* modify position */
  12854.           tl.LowerRow=15;
  12855.           tl.LeftCol=20;
  12856.           tl.RightCol=60;
  12857.           tl.Array=options;             /*initialize TagList2 to our data*/
  12858.           tl.TagArray=tarray;
  12859.           TagList2(TL_DRAW,&tl);        /* draw */
  12860.           Mess=TagList2(TL_ACTIVE,&tl); /* active */
  12861.           if(Mess==TL_OK)
  12862.              {
  12863.              printf("\nThe following options were tagged:\n");
  12864.              for(i=0;i < 7;++i)
  12865.                 {
  12866.                 if(tarray[i])
  12867.                 printf("%s\n",options[i]);
  12868.                 }
  12869.              }
  12870.           else
  12871.              printf("\nOperation canceled by user\n");
  12872.           }
  12873.  
  12874.  
  12875.  
  12876.  
  12877.  
  12878.  
  12879.  
  12880.  
  12881.  
  12882.  
  12883.  
  12884.  
  12885.  
  12886.  
  12887.  
  12888.  
  12889.  
  12890.  
  12891.  
  12892.  
  12893.  
  12894.  
  12895.  
  12896.  
  12897.  
  12898.  
  12899.  
  12900.                                      Page -214-
  12901.  
  12902.  
  12903.  
  12904.  
  12905.  
  12906.                           SCL1 Version 2.0 Reference Manual
  12907.  
  12908.  
  12909.                                                                     TagMenu
  12910.  
  12911.           Function:    TagMenu
  12912.  
  12913.           Purpose:     Displays a menu from which you can tag any or all of
  12914.                        the available options.  An item is toggled on or off
  12915.                        by moving the highlighted bar with the arrow keys
  12916.                        and then pressing the  SPACEBAR or by clicking the
  12917.                        mouse.  The tagged options will be marked with a
  12918.                        check mark.  The menu items can be placed anywhere
  12919.                        in the screen and in any desired order, you are not
  12920.                        limited to placing all the menu options in
  12921.                        successive lines.  Upon exit you can either cancel
  12922.                        the operation or continue.
  12923.  
  12924.           Declaration: int TagMenu(char NormalColor, char ReverseColor,
  12925.                            char HighlightColor, char NumOpt,struct
  12926.                            MenuOpt*, int XMin,int XMax,int YMin,
  12927.                            int YMax);
  12928.  
  12929.           Returns:     The returned value is "0" if the user selects the
  12930.                        accept option and "-1" if the operation is
  12931.                        cancelled.  The calling program must check the first
  12932.                        character of each selection of the structure to find
  12933.                        out if a selection was tagged.
  12934.  
  12935.           Parameters:
  12936.  
  12937.           The menu information must be given as an array of structures as
  12938.           follows:
  12939.  
  12940.                 struct MenuOpt{
  12941.                    int Row,Col;
  12942.                    char *String;
  12943.                    int Letter;
  12944.                    };
  12945.  
  12946.           where:
  12947.  
  12948.                    Row - row position for the menu item (integer).
  12949.  
  12950.                    Col - column position for the menu item (integer).
  12951.  
  12952.                 String - pointer to the menu item text (char).
  12953.  
  12954.                 Letter - letter to be highlighted for fast keyboard
  12955.                          selection of the menu item (integer).
  12956.  
  12957.  
  12958.  
  12959.                                      Page -215-
  12960.  
  12961.  
  12962.  
  12963.  
  12964.  
  12965.                           SCL1 Version 2.0 Reference Manual
  12966.  
  12967.  
  12968.                                                                     TagMenu
  12969.  
  12970.           Note:    The last two options in the menu structure are the exit
  12971.                    control codes to the function.  First the option that
  12972.                    cancels the operation and then the option that accepts
  12973.                    the operation.
  12974.  
  12975.           The parameters passed to the function are:
  12976.  
  12977.                 NColor - color attribute of the menu background and
  12978.                          foreground (integer).
  12979.  
  12980.                 RColor - color attribute of the highlighted item menu bar
  12981.                          (integer).
  12982.  
  12983.                 HColor - color attribute for the highlighted quick
  12984.                          selection menu item letter (integer).
  12985.  
  12986.                 NumOpt - number of menu options (integer).
  12987.  
  12988.                MenuOpt - pointer to the menu structure (char).
  12989.  
  12990.                   XMin - minimum row position of menu area (integer).
  12991.  
  12992.                   XMax - maximum row position of menu area (integer).
  12993.  
  12994.                   YMin - minimum column position of menu area (integer).
  12995.  
  12996.                   YMax - maximum column position of menu area (integer).
  12997.  
  12998.  
  12999.  
  13000.  
  13001.  
  13002.  
  13003.  
  13004.  
  13005.  
  13006.  
  13007.  
  13008.  
  13009.  
  13010.  
  13011.  
  13012.  
  13013.  
  13014.  
  13015.  
  13016.  
  13017.  
  13018.                                      Page -216-
  13019.  
  13020.  
  13021.  
  13022.  
  13023.  
  13024.                           SCL1 Version 2.0 Reference Manual
  13025.  
  13026.  
  13027.                                                                     TagMenu
  13028.  
  13029.           Example:
  13030.  
  13031.           #include <scl1.h>
  13032.           #include <scl1clor.h>
  13033.  
  13034.           struct MenuOpt mo[]={
  13035.              9,35," Option 1 ",'1',
  13036.              10,35," Option 2 ",'2',
  13037.              11,35," Option 3 ",'3',
  13038.              13,35,"  CANCEL  ",'C',
  13039.              14,35,"    OK    ",'O',
  13040.              };
  13041.  
  13042.           main()
  13043.           {
  13044.           int i;
  13045.  
  13046.           Cls(WHITE_BLACK,8,34,15,45);
  13047.           Box(WHITE_BLACK,1,8,34,15,45);
  13048.           if(TagMenu(WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+HIGHLIGHT,5,mo,
  13049.                      35,44,8,15) != -1)
  13050.              {
  13051.              printf("The following options were tagged:\n");
  13052.              for(i=0;i < 3;++i)
  13053.                 {
  13054.                 if(mo[i].String[0] != ' ')
  13055.                    printf("Option %i\n",i+1);
  13056.                 }
  13057.              }
  13058.           else
  13059.              printf("CANCEL was selected\n");
  13060.           }
  13061.  
  13062.  
  13063.  
  13064.  
  13065.  
  13066.  
  13067.  
  13068.  
  13069.  
  13070.  
  13071.  
  13072.  
  13073.  
  13074.  
  13075.  
  13076.  
  13077.                                      Page -217-
  13078.  
  13079.  
  13080.  
  13081.  
  13082.  
  13083.                           SCL1 Version 2.0 Reference Manual
  13084.  
  13085.  
  13086.                                                                  TextWindow
  13087.  
  13088.           Function:    Textwindow
  13089.  
  13090.           Purpose:     Displays text in a window.
  13091.  
  13092.           Declaration: int TextWindow(int Message,TWData *p,...); 
  13093.  
  13094.           Returns:     This is a dialog type function. See Appendix "E" for
  13095.                        the general operation of these functions.  The
  13096.                        return value is a message described in the Messages
  13097.                        section.
  13098.  
  13099.           Parameters:
  13100.  
  13101.           The options must be passed as an array of structures of the type
  13102.           TWData, one array element for each select option:
  13103.  
  13104.           Structure type TWData:
  13105.  
  13106.           typedef struct{
  13107.              int Color;
  13108.              int UpperRow;
  13109.              int LeftCol;
  13110.              int LowerRow;
  13111.              int RightCol;
  13112.              int FrameType;
  13113.              int WrapFlag;
  13114.              int Position;
  13115.              }TWData;
  13116.  
  13117.           where,
  13118.  
  13119.                  Color - color attributes for the window display (integer).
  13120.  
  13121.               UpperRow - upper row coordinate for the window's display
  13122.                          (integer).
  13123.  
  13124.                LeftCol - left column coordinate for the window's display
  13125.                          (integer).
  13126.  
  13127.               LowerRow - lower row coordinate for the window's display
  13128.                          (integer).
  13129.  
  13130.               RightCol - right column coordinate for the window's display
  13131.                          (integer).
  13132.  
  13133.              FrameType - any of the frame types available for the Box or
  13134.                          GSSBox function (integer).
  13135.  
  13136.                                      Page -218-
  13137.  
  13138.  
  13139.  
  13140.  
  13141.  
  13142.                           SCL1 Version 2.0 Reference Manual
  13143.  
  13144.  
  13145.                                                                  TextWindow
  13146.  
  13147.               WrapFlag - flag to indicate if the displayed line will be
  13148.                          truncated or wrapped if the line's length exceeds
  13149.                          the window's width. A value of "0" indicates no
  13150.                          wrap and a value of "1" indicates wrap (integer).
  13151.  
  13152.               Position - structure element used internally to determine the
  13153.                          current position within the window (integer).
  13154.  
  13155.           The following messages can be sent to TextWindow:
  13156.  
  13157.                   TW_INIT - initialize the TWData structure to null and
  13158.                             sets the following default values.
  13159.  
  13160.                              Color - set to white characters in a black
  13161.                                      background or the normal color defined
  13162.                                      by calling SetDialogColors.
  13163.  
  13164.                           LowerRow - set to row "24".
  13165.  
  13166.                           RightCol - set to column "79".
  13167.  
  13168.                         FrameType - set to single line frame.
  13169.  
  13170.                   TW_DRAW - draw the text window to the screen.
  13171.  
  13172.                  TW_WRITE - write the text information to the Text Window.
  13173.  
  13174.                    TW_CLS - clear the window.
  13175.  
  13176.              TW_LINE_DOWN - move the cursor one line down.
  13177.  
  13178.            TW_DRAW_BORDER - draw border around the Text Window.
  13179.  
  13180.                TW_WAIT_ON - text will be written until the window is full
  13181.                             then it stops and waits for a keypress.  When a
  13182.                             key is pressed the window is cleared.
  13183.  
  13184.               TW_WAIT_OFF - when the window is full it returns a
  13185.                             TW_WINDOW_FULL message (default).
  13186.  
  13187.                  TW_RESET - when this message is sent the position
  13188.                             variables are reset to the default value.  If
  13189.                             the exit keys have not been defined they are
  13190.                             set to the default exit keys.
  13191.  
  13192.  
  13193.  
  13194.  
  13195.                                      Page -219-
  13196.  
  13197.  
  13198.  
  13199.  
  13200.  
  13201.                           SCL1 Version 2.0 Reference Manual
  13202.  
  13203.  
  13204.                                                                  TextWindow
  13205.  
  13206.           The following messages can be returned by TextWindow:
  13207.  
  13208.                     TW_OK - the requested action has been performed
  13209.                             successfully.
  13210.  
  13211.            TW_WINDOW_FULL - the Text Window is full.
  13212.  
  13213.           Example:
  13214.  
  13215.           #include <scl1.h>
  13216.           #include <scl1clor.h>
  13217.  
  13218.           char *strings[]={
  13219.           "This strings will be written",
  13220.           "to a Text Window, one by one.",
  13221.           "Several control characters",
  13222.           "like\t\ttab (\\t),\nnew line (\\n)\rand carriage return (\\r)",
  13223.           "are supported."};
  13224.  
  13225.           main()
  13226.           {
  13227.           TWData twd;
  13228.           int i,Mess;
  13229.  
  13230.           TextWindow(TW_INIT,&twd);     /* initialize structure */
  13231.           twd.UpperRow=10;              /* modify position */
  13232.           twd.LowerRow=14;
  13233.           twd.LeftCol=20;
  13234.           twd.RightCol=60;
  13235.  
  13236.              /* in this example we'll check for the WINDOW_FULL message and
  13237.              wait for a key to be pressed before writing anything else */
  13238.  
  13239.           TextWindow(TW_DRAW,&twd);     /* draw */
  13240.           for(i=0;i < 5;++i)
  13241.              {
  13242.              Mess=TextWindow(TW_WRITE,&twd,strings[i]);
  13243.              if(Mess==TW_WINDOW_FULL)   /* window full? */
  13244.                 {
  13245.                 WriteScreen(WHITE_BLACK+HIGHLIGHT,13,21,"Press any key for
  13246.                         more...");
  13247.                 GetKey();
  13248.                 }
  13249.              }
  13250.  
  13251.  
  13252.  
  13253.  
  13254.                                      Page -220-
  13255.  
  13256.  
  13257.  
  13258.  
  13259.  
  13260.                           SCL1 Version 2.0 Reference Manual
  13261.  
  13262.  
  13263.                                                                  TextWindow
  13264.  
  13265.              /* now, we'll get the same effect using the WAIT_ON message,
  13266.                 TextWindow will now stop and wait for a key when the
  13267.                 window is full */
  13268.  
  13269.           TextWindow(TW_DRAW,&twd);
  13270.           TextWindow(TW_WAIT_ON,&twd);
  13271.           for(i=0;i < 5;++i)
  13272.              TextWindow(TW_WRITE,&twd,strings[i]);
  13273.           }
  13274.  
  13275.  
  13276.  
  13277.  
  13278.  
  13279.  
  13280.  
  13281.  
  13282.  
  13283.  
  13284.  
  13285.  
  13286.  
  13287.  
  13288.  
  13289.  
  13290.  
  13291.  
  13292.  
  13293.  
  13294.  
  13295.  
  13296.  
  13297.  
  13298.  
  13299.  
  13300.  
  13301.  
  13302.  
  13303.  
  13304.  
  13305.  
  13306.  
  13307.  
  13308.  
  13309.  
  13310.  
  13311.  
  13312.  
  13313.                                      Page -221-
  13314.  
  13315.  
  13316.  
  13317.  
  13318.  
  13319.                           SCL1 Version 2.0 Reference Manual
  13320.  
  13321.  
  13322.                                                                   TrapInt23
  13323.  
  13324.           Function:    TrapInt23
  13325.  
  13326.           Purpose:     Traps every occurrence of the Control+Break key
  13327.                        combination.  Global variable I23_CtrlBreakFl is
  13328.                        incremented every time this keyboard combination is
  13329.                        pressed.
  13330.  
  13331.           Declaration: void TrapInt23(void);
  13332.  
  13333.           Returns:     Nothing
  13334.  
  13335.           Parameters:  None
  13336.  
  13337.           Example:
  13338.  
  13339.           #include <scl1.h>
  13340.  
  13341.           main()
  13342.           {
  13343.           TrapInt23();
  13344.           printf("Press Ctrl/Break to exit\n");
  13345.           do
  13346.              {
  13347.              }while(I23_CtrlBreakFl==0);
  13348.           }
  13349.  
  13350.  
  13351.  
  13352.  
  13353.  
  13354.  
  13355.  
  13356.  
  13357.  
  13358.  
  13359.  
  13360.  
  13361.  
  13362.  
  13363.  
  13364.  
  13365.  
  13366.  
  13367.  
  13368.  
  13369.  
  13370.  
  13371.  
  13372.                                      Page -222-
  13373.  
  13374.  
  13375.  
  13376.  
  13377.  
  13378.                           SCL1 Version 2.0 Reference Manual
  13379.  
  13380.  
  13381.                                                                   TrapInt24
  13382.  
  13383.           Function:    TrapInt24
  13384.  
  13385.           Purpose:     Critical error interrupt handler.  Displays an error
  13386.                        box showing the critical error that has occurred.
  13387.                        Asks the user if he wants to retry or not the
  13388.                        operation.
  13389.  
  13390.                        This function is useful to avoid the familiar DOS
  13391.                        message "Abort, Retry, Ignore?" from appearing on
  13392.                        your screen.  Also it gives you extra control when
  13393.                        you are performing a series of file operations. If a
  13394.                        file function returns "-1" it means that the user
  13395.                        does not want to retry the operation, in this case
  13396.                        the program can a stop the other I/O operations it
  13397.                        was going to perform.
  13398.  
  13399.                        This function only traps critical errors like: disk
  13400.                        drive door opened, printer off-line, trying to read
  13401.                        an unformatted disk, etc.
  13402.  
  13403.                        To initialize TrapInt24 call it at the beginning of
  13404.                        your program.  It should be called ONLY ONCE.  You
  13405.                        can alter the error box appearance by calling the
  13406.                        SetInt24Colors, Int24ShadowOff and Int24ShadowOn
  13407.                        functions. 
  13408.  
  13409.                        The function saves and restore the screen area where
  13410.                        the error box is displayed. To initialize TrapInt24
  13411.                        call it at the beginning of your program.
  13412.  
  13413.           Declaration: void TrapInt24(void);
  13414.  
  13415.           Returns:     Nothing
  13416.  
  13417.           Parameters:  None
  13418.  
  13419.           Example:
  13420.  
  13421.           #include <scl1.h>
  13422.  
  13423.           main()
  13424.              {
  13425.              TrapInt24();
  13426.              .
  13427.              .
  13428.              }
  13429.           See also SetInt24Colors, Int24ShadowOff and Int24ShadowOn.
  13430.  
  13431.                                      Page -223-
  13432.  
  13433.  
  13434.  
  13435.  
  13436.  
  13437.                           SCL1 Version 2.0 Reference Manual
  13438.  
  13439.  
  13440.                                                                      TSound
  13441.  
  13442.           Function:    TSound
  13443.  
  13444.           Purpose:     Plays a sound of the specified frequency and for a
  13445.                        specified length of time (in hundredths of a
  13446.                        second).
  13447.  
  13448.           Declaration: void TSound(int Frequency, unsigned int Duration);
  13449.  
  13450.           Returns:     Nothing
  13451.  
  13452.           Parameters:
  13453.  
  13454.              Frequency - the note frequency in Hertz (integer).
  13455.  
  13456.               Duration - length of the note in hundredths of a second
  13457.                          (unsigned integer).
  13458.  
  13459.           Example:
  13460.  
  13461.           #include <scl1.h>
  13462.  
  13463.           main()
  13464.              {
  13465.              TSound(1000,100); /* Plays a 1000 Hertz tone for one second */
  13466.              }
  13467.           See the note definitions in header file SCL1SND.H.
  13468.  
  13469.  
  13470.  
  13471.  
  13472.  
  13473.  
  13474.  
  13475.  
  13476.  
  13477.  
  13478.  
  13479.  
  13480.  
  13481.  
  13482.  
  13483.  
  13484.  
  13485.  
  13486.  
  13487.  
  13488.  
  13489.  
  13490.                                      Page -224-
  13491.  
  13492.  
  13493.  
  13494.  
  13495.  
  13496.                           SCL1 Version 2.0 Reference Manual
  13497.  
  13498.  
  13499.                                                                       Video
  13500.  
  13501.           Function:    Video
  13502.  
  13503.           Purpose:     Checks the monitor type.  Detects if the video
  13504.                        adapter in use is either Monochrome or Color. 
  13505.                        Declares and defines the variable VideoSeg (unsigned
  13506.                        int) that holds Video Buffer segment address. (The
  13507.                        VideoConfig function provides additional
  13508.                        information)
  13509.  
  13510.           Declaration: unsigned int Video(void);
  13511.  
  13512.           Returns:     The return value is defined in SCL1.H as MONO if a
  13513.                        monochrome monitor is installed, or COLOR if a color
  13514.                        monitor is installed.
  13515.  
  13516.           Parameters:  None
  13517.  
  13518.           Example:
  13519.  
  13520.           #include <scl1.h>
  13521.  
  13522.           main()
  13523.              {
  13524.              if(Video()==MONO)
  13525.                 printf("You have a monochrome monitor\n");
  13526.              else
  13527.                 printf("You have a color monitor\n");
  13528.              }
  13529.  
  13530.           See also VideoConfig.
  13531.  
  13532.  
  13533.  
  13534.  
  13535.  
  13536.  
  13537.  
  13538.  
  13539.  
  13540.  
  13541.  
  13542.  
  13543.  
  13544.  
  13545.  
  13546.  
  13547.  
  13548.  
  13549.                                      Page -225-
  13550.  
  13551.  
  13552.  
  13553.  
  13554.  
  13555.                           SCL1 Version 2.0 Reference Manual
  13556.  
  13557.  
  13558.                                                                 VideoConfig
  13559.  
  13560.           Function:    VideoConfig
  13561.  
  13562.           Purpose:     Checks the video information of your system.  Fills
  13563.                        a structure with the current video information for
  13564.                        use by other functions.  This function will be
  13565.                        called by the first function that uses direct video
  13566.                        write.  Also sets global variables VC_Monitor,
  13567.                        VC_Mode, VC_Page, VC_Lines, VC_Cols, VC_Retrace and
  13568.                        VC_Segment with the current video information.
  13569.  
  13570.           Declaration: struct VideoData *VideoConfig(void);
  13571.  
  13572.           Returns:     The return value is a pointer to the VideoData
  13573.                        structure.
  13574.  
  13575.           Parameters:
  13576.  
  13577.           The video information is stored in a structure type VideoData:
  13578.           struct VideoData{
  13579.              int Monitor;
  13580.              int Mode;
  13581.              int Page;
  13582.              int Lines;
  13583.              int Cols;
  13584.              unsigned int Segment;
  13585.              int Retrace;
  13586.              };
  13587.  
  13588.           where,
  13589.  
  13590.                monitor - type of monitor detected.  The following types
  13591.                          have been defined in SCL1.H (integer):
  13592.  
  13593.                          VC_MDA   = Monochrome
  13594.                          VC_CGA   = CGA monitor
  13595.                          VC_EGA   = EGA monitor
  13596.                          VC_EGAM  = EGA with monochrome monitor
  13597.                          VC_PGC   = Professional graphic
  13598.                          VC_VGAM  = VGA / monochrome
  13599.                          VC_VGA   = VGA
  13600.                          VC_MCGADC   = MCGA Digital
  13601.                          VC_MCGAAM   = MCGA Analog/mono
  13602.                          VC_MCGAAC   = MCGA Analog/color
  13603.  
  13604.                   Mode - active video mode (integer).
  13605.  
  13606.                   Page - active video page (integer).
  13607.  
  13608.                                      Page -226-
  13609.  
  13610.  
  13611.  
  13612.  
  13613.  
  13614.                           SCL1 Version 2.0 Reference Manual
  13615.  
  13616.  
  13617.                                                                 VideoConfig
  13618.  
  13619.                  Lines - number of rows in current video mode (integer).
  13620.  
  13621.                   Cols - number of columns in current video mode (integer).
  13622.  
  13623.                Segment - segment used by current video mode (unsigned
  13624.                          integer).
  13625.  
  13626.                Retrace - structure element that tells the functions to use
  13627.                          or not to use retrace. If value is to "0" the
  13628.                          direct screen writes will use no retrace if value
  13629.                          is "1" the will use retrace. By default this value
  13630.                          will be set to "0" with all video systems except
  13631.                          VC_CGA.
  13632.  
  13633.           Example:
  13634.  
  13635.           #include <scl1.h>
  13636.  
  13637.           char *vs[]={
  13638.              "",
  13639.              "Monochrome",
  13640.              "CGA",
  13641.              "",
  13642.              "EGA",
  13643.              "EGA - mono",
  13644.              "PGC",
  13645.              "VGA - mono",
  13646.              "VGA",
  13647.              "",
  13648.              "MCGA - digital - color",
  13649.              "MCGA - analog - mono",
  13650.              "MCGA - analog - color",
  13651.              };
  13652.  
  13653.           main()
  13654.           {
  13655.           struct VideoData *vd;
  13656.  
  13657.           vd=VideoConfig();
  13658.           printf("\n  Video system: %s\n",vs[vd->Monitor]);
  13659.           printf("    Video mode: %i\n",vd->Mode);
  13660.           printf("   Active page: %i\n",vd->Page);
  13661.           printf("         Lines: %i\n",vd->Lines);
  13662.           printf("       Columns: %i\n",vd->Cols);
  13663.           printf("Buffer segment: %X\n\n",vd->Segment);
  13664.           }
  13665.           See also Video.
  13666.  
  13667.                                      Page -227-
  13668.  
  13669.  
  13670.  
  13671.  
  13672.  
  13673.                           SCL1 Version 2.0 Reference Manual
  13674.  
  13675.  
  13676.                                                                WaitKeyMouse
  13677.                                                                    WaitTime
  13678.  
  13679.           Function:    WaitKeyMouse
  13680.  
  13681.           Purpose:     Waits for a keystroke or pressing of the left mouse
  13682.                        button.  The function clears the keyboard buffer on
  13683.                        entry.
  13684.  
  13685.           Declaration: unsigned int WaitKeyMouse(void);
  13686.  
  13687.           Returns:     Returns the key's Scan/Ascii code if a key pressed.
  13688.  
  13689.           Parameters:  None
  13690.  
  13691.           Example:
  13692.  
  13693.              WaitKeyMouse();
  13694.  
  13695.           ****************************************************************
  13696.  
  13697.           Function:    WaitTime
  13698.  
  13699.           Purpose:     Sets a delay of X hundredths of a second.
  13700.  
  13701.           Declaration: void WaitTime(unsigned int HSec);
  13702.  
  13703.           Returns:     Nothing
  13704.  
  13705.           Parameters:
  13706.  
  13707.                   HSec - time interval in hundredths of a second.
  13708.  
  13709.           Example:
  13710.  
  13711.              WaitTime(200);  /* Sets a 2 second delay */
  13712.  
  13713.  
  13714.  
  13715.  
  13716.  
  13717.  
  13718.  
  13719.  
  13720.  
  13721.  
  13722.  
  13723.  
  13724.  
  13725.  
  13726.                                      Page -228-
  13727.  
  13728.  
  13729.  
  13730.  
  13731.  
  13732.                           SCL1 Version 2.0 Reference Manual
  13733.  
  13734.  
  13735.                                                                    WFilebox
  13736.  
  13737.           Function:    WFileBox
  13738.  
  13739.           Purpose:     Displays a wide box with the directory information
  13740.                        for loading or selecting files.  Fills a buffer with
  13741.                        the selected file/path.  The function accepts mouse
  13742.                        input.
  13743.  
  13744.           Declaration: int WFileBox(int Message, FBData *p)
  13745.  
  13746.           Returns:     This is a dialog derived function. See Appendix "E"
  13747.                        for a description of the general operation of these
  13748.                        functions.  The return value is a message described
  13749.                        in the Messages section.
  13750.  
  13751.           Parameters:
  13752.  
  13753.           The file box information is given in a structure type FBData as
  13754.           follows:
  13755.  
  13756.           Structure type FBData;
  13757.  
  13758.           typedef struct{
  13759.              int NColor;
  13760.              int RColor;
  13761.              int UpperRow;
  13762.              int LeftCol;
  13763.              int LowerRow;
  13764.              int RightCol;
  13765.              char *Filename;
  13766.              int Attrib;
  13767.              }FBData;
  13768.  
  13769.           where,
  13770.  
  13771.                 NColor - normal color for the file box's display (integer).
  13772.  
  13773.                 RColor - reversed color for the file box's display
  13774.                          (integer).
  13775.  
  13776.               UpperRow - upper row coordinate for the file box's display
  13777.                          (integer).
  13778.  
  13779.  
  13780.  
  13781.  
  13782.  
  13783.  
  13784.  
  13785.                                      Page -229-
  13786.  
  13787.  
  13788.  
  13789.  
  13790.  
  13791.                           SCL1 Version 2.0 Reference Manual
  13792.  
  13793.  
  13794.                                                                    WFilebox
  13795.  
  13796.                LeftCol - left column coordinate for the file box's display
  13797.                          (integer).
  13798.  
  13799.               LowerRow - lower row coordinate for the file box's display
  13800.                          (integer).
  13801.  
  13802.               RightCol - right column coordinate for the file box's display
  13803.                          (integer).
  13804.  
  13805.               Filename - pointer to buffer to hold selected filename. The
  13806.                          search string is placed in the buffer before
  13807.                          calling the function.  If an empty buffer is used
  13808.                          (NO SEARCH STRING SPECIFIED), the function will
  13809.                          place the default path and the "*.*" search string
  13810.                          in the buffer.
  13811.  
  13812.  
  13813.                 Attrib - file attributes as defined by the DOS. Please
  13814.                          refer to Appendix "A", FILE FUNCTIONS, for more
  13815.                          details (integer).
  13816.  
  13817.           Messages:
  13818.  
  13819.           The following messages can be sent to WFilebox:
  13820.  
  13821.                   FB_INIT - initialize the FBData structure to NULL and set
  13822.                             the following default values:
  13823.  
  13824.                             NColor - set to white characters in a black
  13825.                                      background or the normal color defined
  13826.                                      by calling SetDialogColors.
  13827.  
  13828.                             RColor - set to black characters in a white
  13829.                                      background or the reversed color
  13830.                                      defined by calling SetDialogColors.
  13831.  
  13832.                            LeftCol - set to column "20" for 80 column
  13833.                                      displays or to column "0" for 40
  13834.                                      column displays.
  13835.  
  13836.                           LowerRow - set to row "24" for 25 row displays or
  13837.                                      to row "42" for 43 row displays.
  13838.  
  13839.                           RightCol - set to column "39" for 40 column
  13840.                                      display and "79" for 80 column
  13841.                                      displays.
  13842.  
  13843.  
  13844.                                      Page -230-
  13845.  
  13846.  
  13847.  
  13848.  
  13849.  
  13850.                           SCL1 Version 2.0 Reference Manual
  13851.  
  13852.  
  13853.                                                                    WFilebox
  13854.  
  13855.                             Attrib - files and sub-directories.
  13856.  
  13857.                   FB_DRAW - draw the Filebox to the screen.
  13858.  
  13859.                 FB_ACTIVE - browse through the displayed filenames and
  13860.                             permit selection or cancellling of the
  13861.                             operation using the following keys:
  13862.  
  13863.                          Key                      action
  13864.  
  13865.                        Up Arrow         cursor one item up.
  13866.                        Down Arrow       cursor one item down.
  13867.                        Left Arrow       cursor one item to the left.
  13868.                        Right Arrow      cursor one item to the right.
  13869.                        END              cursor to end of file list.
  13870.                        HOME             cursor to beginning of list.
  13871.  
  13872.           The following messages can be returned by WFileBox:
  13873.  
  13874.                     FB_OK - the action requested has been performed and no
  13875.                             selection has been made.
  13876.  
  13877.                 FB_CANCEL - the operation has been cancelled.
  13878.  
  13879.           Example:
  13880.  
  13881.           #include <scl1.h>
  13882.           #include <scl1clor.h>
  13883.  
  13884.           char Buffer[80];
  13885.           int Color1=WHITE_BLACK;
  13886.           int Color2=BLACK_WHITE;
  13887.  
  13888.           main()
  13889.              {
  13890.              FBData fbd;
  13891.              WFileBox(FB_INIT,&fbd); /* initialize the FBData structure */
  13892.              fbd.NColor=Color1;      /* change display colors */
  13893.              fbd.RColor=Color2;
  13894.              fbd.Filename=Buffer;   /* set buffer to hold directory info */
  13895.              fbd.Attrib=F_READ_ONLY+F_HIDDEN+F_SYSTEM+F_DIRECTORY;
  13896.                                     /* set files attributes */
  13897.              WFileBox(FB_DRAW,&fbd);   /* display FileBox */
  13898.              WFileBox(FB_ACTIVE,&fbd); /* let user make a selection */
  13899.              }
  13900.  
  13901.  
  13902.  
  13903.                                      Page -231-
  13904.  
  13905.  
  13906.  
  13907.  
  13908.  
  13909.                           SCL1 Version 2.0 Reference Manual
  13910.  
  13911.  
  13912.                                                                      Window
  13913.           Function:    Window
  13914.  
  13915.           Purpose:     Saves, clears and restores a window.
  13916.  
  13917.           Declaration: void Window(int Color,int UpperRow,int LeftCol,
  13918.                             int LowerRow, int RightCol, char* Flag,
  13919.                             char* Buffer);
  13920.  
  13921.           Returns:     Nothing
  13922.  
  13923.           Parameters:
  13924.  
  13925.                  Color - color attribute for the area to be cleared
  13926.                          (integer).
  13927.  
  13928.               UpperRow - upper left row coordinate of the area (integer).
  13929.  
  13930.                LeftCol - upper left column coordinate of the area
  13931.                          (integer).
  13932.  
  13933.               LowerRow - lower right row coordinate of the area (integer).
  13934.  
  13935.               RightCol - lower right column coordinate of the area
  13936.                          (integer).
  13937.  
  13938.                   Flag - pointer to a variable that holds the action to be
  13939.                          performed:
  13940.  
  13941.                        0  -> save and clear area.
  13942.                        -2 -> save area only.
  13943.                        1  -> restore area (saved and cleared).
  13944.                        -1 -> restore area (saved only).
  13945.  
  13946.                 Buffer - pointer to a buffer to hold the screen
  13947.                          information.
  13948.  
  13949.  
  13950.  
  13951.  
  13952.  
  13953.  
  13954.  
  13955.  
  13956.  
  13957.  
  13958.  
  13959.  
  13960.  
  13961.  
  13962.                                      Page -232-
  13963.  
  13964.  
  13965.  
  13966.  
  13967.  
  13968.                           SCL1 Version 2.0 Reference Manual
  13969.  
  13970.  
  13971.                                                                      Window
  13972.  
  13973.           Notes:
  13974.  
  13975.              1. The flag is toggled automatically every time the function
  13976.                 is called.
  13977.  
  13978.              2. The buffer size is the Number of characters * 2
  13979.  
  13980.           Example:
  13981.  
  13982.           #include <scl1.h>
  13983.           #include <scl1keys.h>
  13984.           #include <scl1clor.h>
  13985.  
  13986.           /* screen data is stored in these buffers, use W_BUF_SIZE macro
  13987.              to calculate buffer size */
  13988.  
  13989.           char buffer1[W_BUF_SIZE(0,0,24,79)];
  13990.           char buffer2[W_BUF_SIZE(9,26,15,52)];
  13991.  
  13992.           main()
  13993.           {
  13994.           char WFlag1=-2;     /* save do not clear screen */
  13995.           char WFlag2=0;      /* save and clear screen */
  13996.  
  13997.           Window(BLACK_WHITE,0,0,24,79,&WFlag1,buffer1);
  13998.           FillBlock(WHITE_BLACK,0,0,24,79,'X');
  13999.           WriteScreenLen(BLACK_WHITE,24,0,70," The whole screen has
  14000.                          been saved, press any key...");
  14001.           GetKey();
  14002.  
  14003.           Window(WHITE_BLACK,9,26,15,52,&WFlag2,buffer2);
  14004.           WriteScreenLen(BLACK_WHITE,24,0,70," A second window was SAVED
  14005.                          AND CLEARED, press any key to restore it...");
  14006.           GetKey();
  14007.  
  14008.           Window(WHITE_BLACK,9,26,15,52,&WFlag2,buffer2);
  14009.  
  14010.           WriteScreenLen(BLACK_WHITE,24,0,70," Press any key to restore
  14011.                          the screen...");
  14012.           GetKey();
  14013.  
  14014.           Window(BLACK_WHITE,0,0,24,79,&WFlag1,buffer1);
  14015.           }
  14016.  
  14017.  
  14018.  
  14019.  
  14020.  
  14021.                                      Page -233-
  14022.  
  14023.  
  14024.  
  14025.  
  14026.  
  14027.                           SCL1 Version 2.0 Reference Manual
  14028.  
  14029.  
  14030.                                                                   WriteChar
  14031.  
  14032.           Function:    WriteChar
  14033.  
  14034.           Purpose:     Writes a character directly to the screen buffer a
  14035.                        specified number of times.
  14036.  
  14037.           Declaration: void WriteChar(int Color, int Row, int Col,
  14038.                             int Count, int Character);
  14039.  
  14040.           Returns:     Nothing
  14041.  
  14042.           Parameters:
  14043.  
  14044.                  Color - color attribute for the character to be displayed
  14045.                          (integer).
  14046.  
  14047.                    Row - row coordinate of position to start display
  14048.                          (integer).
  14049.  
  14050.                    Col - column coordinate of position to start display
  14051.                          (integer).
  14052.  
  14053.                  Count - number of times the character is written
  14054.                          (integer).
  14055.  
  14056.              Character - the character to be displayed (integer).
  14057.  
  14058.           Example:
  14059.  
  14060.           #include <scl1.h>
  14061.           #include <scl1clor.h>
  14062.  
  14063.           int Color1=WHITE_BLACK;
  14064.  
  14065.           main()
  14066.              {
  14067.              WriteChar(Color1,10,0,80,'-');
  14068.              }
  14069.  
  14070.           /* Writes 80 dashes to the screen starting in line 10, column 0*/
  14071.  
  14072.  
  14073.  
  14074.  
  14075.  
  14076.  
  14077.  
  14078.  
  14079.  
  14080.                                      Page -234-
  14081.  
  14082.  
  14083.  
  14084.  
  14085.  
  14086.                           SCL1 Version 2.0 Reference Manual
  14087.  
  14088.  
  14089.                                                                   WriteFile
  14090.  
  14091.           Function:    WriteFile
  14092.  
  14093.           Purpose:     Writes to a file.  The function can also be used to
  14094.                        write to the standard printer, console or any other
  14095.                        standard device if the proper handle number is
  14096.                        specified.
  14097.  
  14098.           Declaration: int WriteFile(int Handle,char *Buffer,
  14099.                            unsigned int Bytes);
  14100.  
  14101.           Returns:     The return value is "0" if no error occurs or the
  14102.                        DOS error code if an error occurs.  (See Appendix
  14103.                        "A", FILE FUNCTIONS, for more information).
  14104.  
  14105.           Parameters:
  14106.  
  14107.                 Handle - handle number given by DOS when you open or create
  14108.                          a file (integer).
  14109.  
  14110.                 Buffer - pointer to the buffer that will hold the data.
  14111.  
  14112.                  Bytes - number of bytes to write (unsigned integer).
  14113.  
  14114.           Example:
  14115.  
  14116.           #include <scl1.h>
  14117.           /* This is the source code of the Buf2Disk function */
  14118.  
  14119.           Buf2Disk(char *Filename,char *Buffer,unsigned int Bytes)
  14120.              {
  14121.              int i,handle;
  14122.  
  14123.              if(i=CreateFile(Filename,&handle,F_ARCHIVE))
  14124.                 return(i);
  14125.  
  14126.              if(i=WriteFile(handle,Buffer,Bytes))
  14127.                 {
  14128.                 if(i > 0)
  14129.                    CloseFile(handle);
  14130.                        return(i);
  14131.                 }
  14132.              return(CloseFile(handle));
  14133.              }
  14134.  
  14135.  
  14136.  
  14137.  
  14138.  
  14139.                                      Page -235-
  14140.  
  14141.  
  14142.  
  14143.  
  14144.  
  14145.                           SCL1 Version 2.0 Reference Manual
  14146.  
  14147.  
  14148.                                                                 WriteOffLen
  14149.  
  14150.           Function:    WriteOffLen
  14151.  
  14152.           Purpose:     Writes a string directly to the video buffer. The
  14153.                        length to display is specified.  If the string is
  14154.                        shorter than the specified length, the remaining
  14155.                        spaces are filled with the space character. The
  14156.                        display position is specified as an offset from the
  14157.                        home position.
  14158.  
  14159.           Declaration: void WriteOffLen(int Color, int Offset, int Count,
  14160.                             char * String);
  14161.  
  14162.           Returns:     Nothing
  14163.  
  14164.           Parameters:
  14165.  
  14166.                  Color - color attribute of the desired display (integer).
  14167.  
  14168.                 Offset - offset from the home position where to display the
  14169.                          string.  The offset is calculated as follows:
  14170.                          number of columns multiplied by "2" multiplied by
  14171.                          the number of rows plus the desired column
  14172.                          position multiplied by "2" (integer).
  14173.  
  14174.                  Count - length to display (integer).
  14175.  
  14176.                 String - pointer to the string to be displayed.
  14177.  
  14178.           Example:
  14179.  
  14180.           #include <scl1.h>
  14181.           #include <scl1clor.h>
  14182.  
  14183.           int Color1=WHITE_BLACK;
  14184.  
  14185.           main()
  14186.              {
  14187.              WriteOffLen(Color1,1500,15,"This is a test. ");
  14188.              }
  14189.  
  14190.           /* Displays the string with a length of 15 character in position
  14191.              offset 1500 */
  14192.  
  14193.  
  14194.  
  14195.  
  14196.  
  14197.  
  14198.                                      Page -236-
  14199.  
  14200.  
  14201.  
  14202.  
  14203.  
  14204.                           SCL1 Version 2.0 Reference Manual
  14205.  
  14206.  
  14207.                                                                 WriteOffset
  14208.  
  14209.           Function:    WriteOffset
  14210.  
  14211.           Purpose:     Writes a character directly to the video buffer. The
  14212.                        display position is specified as an offset from the
  14213.                        home position.
  14214.  
  14215.           Declaration: void WriteOffset(int Color, int Offset,
  14216.                             int Character);
  14217.  
  14218.           Returns:     Nothing
  14219.  
  14220.           Parameters:
  14221.  
  14222.                  Color - color attribute of the desired display (integer).
  14223.  
  14224.                 Offset - offset from the home position where to display the
  14225.                          string.  The offset is calculated as follows:
  14226.                          number of columns multiplied by "2" multiplied by
  14227.                          the number of rows plus the desired column
  14228.                          position multiplied by "2" (integer).
  14229.  
  14230.              Character - character to be displayed (integer).
  14231.  
  14232.           Example:
  14233.  
  14234.           #include <scl1.h>
  14235.           #include <scl1clor.h>
  14236.  
  14237.           #define ROW  10
  14238.           #define COL  60
  14239.  
  14240.           char string[]="IN GIRUM IMUS NOCTE ET CONSUMIMUR IGNI";
  14241.  
  14242.           main()
  14243.           {
  14244.           int offset,i;
  14245.  
  14246.           InitVideo();
  14247.           WriteScreen(BLACK_WHITE,ROW-1,23,string);
  14248.           offset = ROW * VC_Cols * 2 + COL  * 2;
  14249.           for(i=0;i < sizeof(string)-1;++i,offset-=2)
  14250.              WriteOffset(BLACK_WHITE,offset,string[i]);
  14251.           }
  14252.  
  14253.  
  14254.  
  14255.  
  14256.  
  14257.                                      Page -237-
  14258.  
  14259.  
  14260.  
  14261.  
  14262.  
  14263.                           SCL1 Version 2.0 Reference Manual
  14264.  
  14265.  
  14266.                                                                 WriteScreen
  14267.  
  14268.           Function:    WriteScreen
  14269.  
  14270.           Purpose:     Writes a string directly to the video buffer.
  14271.                        Supports control character "\n".
  14272.  
  14273.           Declaration: void WriteScreen(int Attribute, int Row,
  14274.                            int Column, char* StringAdr);
  14275.  
  14276.           Returns:     Nothing
  14277.  
  14278.           Parameters:
  14279.  
  14280.              Attribute - color attribute of the desired display (integer).
  14281.  
  14282.                    Row - row coordinate where to display the string
  14283.                          (integer).
  14284.  
  14285.                 Column - column coordinate where to display the string
  14286.                          (integer).
  14287.  
  14288.              StringAdr - pointer to the string to be displayed.
  14289.  
  14290.           Example:
  14291.  
  14292.           #include <scl1.h>
  14293.           #include <scl1clor.h>
  14294.  
  14295.           char Mess[]="SCL1's screen related functions will let you:\n\n"
  14296.                       "   ∙ Write directly to the screen.\n\n"
  14297.                       "   ∙ Draw boxes.\n\n"
  14298.                       "   ∙ Clear or scroll any area of your screen.\n\n"
  14299.                       "   ∙ Save and restore any screen area.\n\n"
  14300.                       "   ∙ Control cursor size and many more...";
  14301.  
  14302.           int Color1=WHITE_BLACK;
  14303.  
  14304.           main()
  14305.              {
  14306.              WriteScreen(Color1,4,20,Mess3);
  14307.              }
  14308.  
  14309.           /* Displays the string Mess3[] in row 4, column 20 */
  14310.  
  14311.  
  14312.  
  14313.  
  14314.  
  14315.  
  14316.                                      Page -238-
  14317.  
  14318.  
  14319.  
  14320.  
  14321.  
  14322.                           SCL1 Version 2.0 Reference Manual
  14323.  
  14324.  
  14325.                                                              WriteScreenLen
  14326.  
  14327.           Function:    WriteScreenLen
  14328.  
  14329.           Purpose:     Writes a string directly to the video buffer. The
  14330.                        length to display is specified.  If the string is
  14331.                        shorter than the specified length, the remaining
  14332.                        spaces are filled with the space character.
  14333.  
  14334.           Declaration: void WriteScreenLen(int Color, int Row, int Col,
  14335.                             int Count,char *String);
  14336.  
  14337.           Returns:     Nothing
  14338.  
  14339.           Parameters:
  14340.  
  14341.                  Color - color attribute of the desired display (integer).
  14342.  
  14343.                    Row - row coordinate where to display the string
  14344.                          (integer).
  14345.  
  14346.                    Col - column coordinate where to display the string
  14347.                          (integer).
  14348.  
  14349.                  Count - length to display (integer).
  14350.  
  14351.                 String - pointer to the string to be displayed.
  14352.  
  14353.           Example:
  14354.  
  14355.           #include <scl1.h>
  14356.           #include <scl1clor.h>
  14357.  
  14358.           char string1[]="Only the characters that fit inside the box will
  14359.                           written to the screen.";
  14360.           char string2[]="WriteScreenLen blanks the screen if the
  14361.                           string\nis shorter than the length specified:";
  14362.           char *strings[]={"1234567890",
  14363.                             "12345678",
  14364.                             "12345"};
  14365.  
  14366.  
  14367.  
  14368.  
  14369.  
  14370.  
  14371.  
  14372.  
  14373.  
  14374.  
  14375.                                      Page -239-
  14376.  
  14377.  
  14378.  
  14379.  
  14380.  
  14381.                           SCL1 Version 2.0 Reference Manual
  14382.  
  14383.  
  14384.                                                              WriteScreenLen
  14385.  
  14386.           main()
  14387.           {
  14388.           int TopRow,LeftCol,BottomRow,wide,i;
  14389.  
  14390.           for(TopRow=LeftCol=4,BottomRow=TopRow+2,wide=72;wide > 4;
  14391.               wide-=2,++LeftCol)
  14392.              {
  14393.              Box(BLACK_WHITE,0,TopRow,LeftCol,BottomRow,LeftCol+wide);
  14394.              WriteScreenLen(BLACK_WHITE,TopRow+1,LeftCol+1,wide-1,string1);
  14395.              GetKey();
  14396.              }
  14397.           Cls(BLACK_WHITE,10,10,14,70);
  14398.           WriteScreen(BLACK_WHITE,11,17,string2);
  14399.           for(i=0;i < 3;++i)
  14400.              {
  14401.              WriteScreenLen(BLACK_WHITE,13,35,34,strings[i]);
  14402.              GetKey();
  14403.              }
  14404.           }
  14405.  
  14406.  
  14407.  
  14408.  
  14409.  
  14410.  
  14411.  
  14412.  
  14413.  
  14414.  
  14415.  
  14416.  
  14417.  
  14418.  
  14419.  
  14420.  
  14421.  
  14422.  
  14423.  
  14424.  
  14425.  
  14426.  
  14427.  
  14428.  
  14429.  
  14430.  
  14431.  
  14432.  
  14433.  
  14434.                                      Page -240-
  14435.  
  14436.  
  14437.  
  14438.  
  14439.  
  14440.                           SCL1 Version 2.0 Reference Manual
  14441.  
  14442.  
  14443.                                                                       YesNo
  14444.  
  14445.           Function:    YesNo
  14446.  
  14447.           Purpose:     Displays a YES/NO query box with mouse control
  14448.                        buttons.  The original screen is restored on exit.
  14449.  
  14450.           Declaration: int YesNo(int NColor,int RColor,int Selection,
  14451.                            char *p);
  14452.  
  14453.           Returns: A value of "1" is returned if the YES box is selected or
  14454.                    clicked with the mouse and a value of "2" if the NO box
  14455.                    is selected or clicked.
  14456.  
  14457.           Parameters:
  14458.  
  14459.                 NColor - color attribute for the YES/NO box (integer).
  14460.  
  14461.                 RColor - color attribute of the selected option (integer).
  14462.  
  14463.              Selection - default selection (integer).
  14464.  
  14465.                      p - pointer to the question whose answer is seeked.
  14466.  
  14467.           Example:
  14468.  
  14469.           #include <scl1.h>
  14470.           #include <scl1clor.h>
  14471.  
  14472.           #define YES 1
  14473.           #define NO  2
  14474.  
  14475.           int Color1=WHITE_BLACK;
  14476.           int Color2=BLACK_WHITE;
  14477.  
  14478.           main()
  14479.           {
  14480.           do
  14481.              {
  14482.              if(YesNo(Color1,Color2,"Turn YesNo Box\nShadow On?") == YES)
  14483.                 YesNoShadowOn();
  14484.              if(YesNo(Color1,Color2,"Turn YesNo Box\nShadow Off?") == YES)
  14485.                 YesNoShadowOff();
  14486.              }while(YesNo(Color1,Color2,NO,"Exit to DOS?") != YES);
  14487.           }
  14488.  
  14489.           See YesNoShadowOff and YesNoShadowOn
  14490.  
  14491.  
  14492.  
  14493.                                      Page -241-
  14494.  
  14495.  
  14496.  
  14497.  
  14498.  
  14499.                           SCL1 Version 2.0 Reference Manual
  14500.  
  14501.  
  14502.                                                              YesNoShadowOff
  14503.                                                               YesNoShadowOn
  14504.  
  14505.           Function:    YesNoShadowOff
  14506.                        YesNoShadowOn
  14507.  
  14508.           Purpose:     Displays or disable a shadow effect when using the
  14509.                        YesNo function.  After any of these functions are
  14510.                        called all subsequent calls to the YesNo function
  14511.                        will be displayed with (or without) a shadow effect.
  14512.  
  14513.           Declaration: void YesNoShadowOff(void);
  14514.                        void YesNoShadowOn(void);
  14515.  
  14516.           Returns:     Nothing.
  14517.  
  14518.           Parameters:  None.
  14519.  
  14520.           Example:
  14521.  
  14522.  
  14523.           #include <scl1.h>
  14524.           #include <scl1clor.h>
  14525.  
  14526.           #define YES 1
  14527.           #define NO  2
  14528.  
  14529.           int Color1=WHITE_BLACK;
  14530.           int Color2=BLACK_WHITE;
  14531.  
  14532.           main()
  14533.           {
  14534.           do
  14535.              {
  14536.              if(YesNo(Color1,Color2,"Turn YesNo Box\nShadow On?") == YES)
  14537.                 YesNoShadowOn();
  14538.              if(YesNo(Color1,Color2,"Turn YesNo Box\nShadow Off?") == YES)
  14539.                 YesNoShadowOff();
  14540.              }while(YesNo(Color1,Color2,NO,"Exit to DOS?") != YES);
  14541.           }
  14542.  
  14543.           See YesNo.
  14544.  
  14545.  
  14546.  
  14547.  
  14548.  
  14549.  
  14550.  
  14551.  
  14552.                                      Page -242-
  14553.  
  14554.  
  14555.  
  14556.  
  14557.  
  14558.                                     Appendix "A"
  14559.  
  14560.  
  14561.                                FILE RELATED FUNCTIONS
  14562.  
  14563.           SCL1's file related functions rely on DOS services to work with
  14564.           files.  They provide an alternative to the standard library
  14565.           functions with a main objective of providing an easier way to
  14566.           trap and display error related information.
  14567.  
  14568.           You can classify errors in two groups; critical and non-
  14569.           critical.  Critical errors are those that generate an interrupt
  14570.           0x24 like, for example, a disk drive door left opened.  This is
  14571.           the type of error that generates the DOS message "Retry, Abort,
  14572.           Ignore?".  Non-critical errors are reported by the system but do
  14573.           not generate an interrupt 0x24 like, for example, not finding a
  14574.           file.
  14575.  
  14576.           SCL1 functions deals with non-critical errors in a simple way. 
  14577.           Most file functions return zero if the operation was successful,
  14578.           otherwise they return the DOS error code that identifies the type
  14579.           of error.  Your program can then process the error code or you
  14580.           can call the ErrorBox function that will display the error
  14581.           message.  You can add your own errors to ErrorBox default error
  14582.           messages (see ErrorBox).
  14583.  
  14584.           To deal with DOS critical errors, SCL1 has the TrapInt24
  14585.           function.  Call this function at the beginning of your program
  14586.           (it must be done only once) and any subsequent critical errors
  14587.           will be handled by SCL1.  Now if DOS generates an interrupt 0x24,
  14588.           instead of its standard message, a window will be opened in the
  14589.           screen's center and a message indicating the type of error, disk
  14590.           or printer related, and asking the user if he wants or not to
  14591.           retry operation will be displayed.  On exit the original screen
  14592.           will be restored.
  14593.  
  14594.           Once you have initialized TrapInt24, SCL1's file related
  14595.           functions will return -1 to indicate a DOS critical error if the
  14596.           user decided NOT TO retry the operation.  If the user decides to
  14597.           retry the operation and it is completed successfully, no error
  14598.           code is reported.
  14599.  
  14600.           As you see, trapping critical errors and non-critical errors can
  14601.           be easily integrated to your program by using TrapInt24 and
  14602.           ErrorBox.  SCL1's way of displaying error message is specially
  14603.           appropriate for programs that are not command-line oriented. 
  14604.           Also notice that you don't have to use ErrorBox when a critical
  14605.           error is reported since TrapInt24 has its own way of displaying
  14606.           error messages.
  14607.  
  14608.           Refer to the DOS Technical Reference for more information about
  14609.           error code numbers.
  14610.  
  14611.                                      Page -243-
  14612.  
  14613.  
  14614.  
  14615.  
  14616.  
  14617.                                     Appendix "A"
  14618.  
  14619.           The following pseudo-code shows how to deal with errors:
  14620.  
  14621.                 Returned error code > than 0 ?
  14622.  
  14623.                    Call ErrorBox with error number.
  14624.  
  14625.                 Error code = -1 ?
  14626.  
  14627.                    DOS Critical error, the user choose not to retry
  14628.                    operation. No need to call ErrorBox since the error
  14629.                    message has already been displayed by TrapInt24.
  14630.  
  14631.                 else
  14632.  
  14633.                    Operation was successful.
  14634.  
  14635.           The following list show the most common DOS error codes:
  14636.  
  14637.                    2   File not found
  14638.                    3   Path not found
  14639.                    4   No handles left
  14640.                    5   Access denied
  14641.                    6   Invalid handle
  14642.                    15  Invalid drive
  14643.                    16  Attempt to remove current directory
  14644.                    29  Write Fault
  14645.                    30  Read Fault
  14646.  
  14647.              SCL1's Error codes:
  14648.  
  14649.                    255   File too big   (used by File2Buf)
  14650.                    -1  Dos Critical error
  14651.                    -2  Drive not valid (used by GetDiskFreeSpace)
  14652.  
  14653.           SCL1 gives you direct access to DOS file related functions. You
  14654.           need to understand DOS's way of working with files for using
  14655.           them.  There are many books that could help you. The general
  14656.           procedure is:
  14657.  
  14658.              First you must open or create a file.  Use OpenFile or
  14659.              CreateFile to do it.  The first function opens an existing
  14660.              file (error is reported if the file is not found ), while the
  14661.              second one creates a file if the file is not found or
  14662.              truncates an existing file to 0.  When you open or create a
  14663.              file DOS gives you a "Handle".  A handle is a number that you
  14664.              will use to refer to this file when performing any other
  14665.              operations like reading, writing, etc.
  14666.  
  14667.  
  14668.  
  14669.  
  14670.                                      Page -244-
  14671.  
  14672.  
  14673.  
  14674.  
  14675.  
  14676.                                     Appendix "A"
  14677.  
  14678.              Once you have a handle to a file you can write or read data.
  14679.              To do it use ReadFile or WriteFile. This functions will read
  14680.              or write any number of bytes to or from a buffer you specify.
  14681.              Files functions under DOS have a read/write pointer. In other
  14682.              words, when you read 200 bytes the file pointer will point to
  14683.              byte 201. This means that next time you read, you will read
  14684.              byte 201. This pointer is automatically moved by ReadFile and
  14685.              WriteFile. You can move this pointer yourself using MoveFilePt
  14686.              and MoveFilePt2Offset.
  14687.  
  14688.              Once you have finished working with your file, you must close
  14689.              the file by using CloseFile.
  14690.  
  14691.              As you see working with files under DOS is a three step
  14692.              process: 1) Open/Create File, 2) Read/Write, 3) Close File.
  14693.  
  14694.              SCL1 offers another, and probably easier, way to work with
  14695.              files. You can read a file to a buffer or write a buffer to a
  14696.              file in just one step using File2Buf and Buf2Disk. You don't
  14697.              have to care about opening or closing files with this
  14698.              functions. But you will have to read or write the whole
  14699.              file/buffer when you use them.
  14700.  
  14701.  
  14702.  
  14703.  
  14704.  
  14705.  
  14706.  
  14707.  
  14708.  
  14709.  
  14710.  
  14711.  
  14712.  
  14713.  
  14714.  
  14715.  
  14716.  
  14717.  
  14718.  
  14719.  
  14720.  
  14721.  
  14722.  
  14723.  
  14724.  
  14725.  
  14726.  
  14727.  
  14728.  
  14729.                                      Page -245-
  14730.  
  14731.  
  14732.  
  14733.  
  14734.  
  14735.                                     Appendix "B"
  14736.  
  14737.  
  14738.                                MOUSE RELATED FUNCTIONS
  14739.  
  14740.           All SCL1 mouse related functions are based on an interrupt
  14741.           service routine (ISR) that updates a series of variables
  14742.           according to the mouse current state.  If you do not initialize
  14743.           this ISR you would not be able to use any mouse related routine. 
  14744.           Mouse initialization can be performed in several ways. 
  14745.  
  14746.           The CheckMouse function can be used to check if the mouse
  14747.           hardware/software is installed:
  14748.  
  14749.                    if(CheckMouse())
  14750.                        we have a mouse !
  14751.  
  14752.           Once you have verified that the mouse is installed you should
  14753.           reset the mouse software to its defaults using ResetMouse and
  14754.           then proceed to install the ISR using SetMouseIsr:
  14755.  
  14756.                    if(CheckMouse())
  14757.                        {
  14758.                        ResetMouse();
  14759.                        SetMouseIsr();
  14760.  
  14761.           Now you can call any mouse related functions. You can begin by
  14762.           calling ShowMouse to make the mouse visible.
  14763.  
  14764.           NOTE: Before returning to DOS should program must un-install the
  14765.           ISR using ResetMouse(). Failure to do so might cause
  14766.           unpredictable problems.
  14767.  
  14768.           All these steps can be simplified by using InitMouse function.
  14769.           This function performs all the operations described above
  14770.           including resetting the ISR:
  14771.  
  14772.           If you want a visible mouse cursor use:
  14773.  
  14774.                 InitMouse(IM_SHOW);
  14775.  
  14776.           If you want an invisible mouse cursor use:
  14777.  
  14778.                 InitMouse(IM_NO_SHOW);
  14779.  
  14780.           Once the mouse is initialized a series of variables are updated
  14781.           according to mouse events (see SetMouseIsr). Your program can
  14782.           check these variables at any moment to read the mouse position
  14783.           and the mouse buttons state.
  14784.  
  14785.  
  14786.  
  14787.  
  14788.                                      Page -246-
  14789.  
  14790.  
  14791.  
  14792.  
  14793.  
  14794.                                     Appendix "B"
  14795.  
  14796.           NOTE: If you change video modes you should reset the mouse and
  14797.           re-initialize it.  The re-initialization MUST NOT be done using
  14798.           InitMouse:
  14799.  
  14800.                 InitMouse(IM_SHOW);
  14801.                    .
  14802.                    .
  14803.                    ResetMouse();
  14804.                    SetVideoMode(1);
  14805.  
  14806.                    if(CheckMouse())
  14807.                        {
  14808.                        ResetMouse();
  14809.                        SetMouseIsr();
  14810.                        ShowMouse();
  14811.                        }
  14812.  
  14813.  
  14814.  
  14815.  
  14816.  
  14817.  
  14818.  
  14819.  
  14820.  
  14821.  
  14822.  
  14823.  
  14824.  
  14825.  
  14826.  
  14827.  
  14828.  
  14829.  
  14830.  
  14831.  
  14832.  
  14833.  
  14834.  
  14835.  
  14836.  
  14837.  
  14838.  
  14839.  
  14840.  
  14841.  
  14842.  
  14843.  
  14844.  
  14845.  
  14846.  
  14847.                                      Page -247-
  14848.  
  14849.  
  14850.  
  14851.  
  14852.  
  14853.                                     Appendix "C"
  14854.  
  14855.  
  14856.                               SCREEN RELATED FUNCTIONS
  14857.  
  14858.           All SCL1's screen related functions write directly to the video
  14859.           buffer.  Configuration according to monitor type is done
  14860.           automatically when the first screen related function is called.
  14861.           During this configuration, SCL1's Video function will determine
  14862.           the type of monitor, the video buffer memory address and wether
  14863.           it is necessary to wait for the monitor retrace to avoid snow.
  14864.  
  14865.           To learn about the video configuration your program will be using
  14866.           you should call VideoConfig. This function returns a pointer to a
  14867.           structure that holds the information about the video adapter
  14868.           you'll be using. The structure format is as follows:
  14869.  
  14870.           struct VideoData{
  14871.              int Monitor;            /* Monitor type */
  14872.              int Mode;               /* Active video mode */
  14873.              int Page;               /* Active video page */
  14874.              int Lines;              /* Number of lines in video mode */
  14875.              int Cols;               /* Number of columns in video mode */
  14876.              unsigned int Segment;   /* video buffer segment address */
  14877.              int Retrace;            /* =1 if retrace is to be done */
  14878.              };
  14879.  
  14880.           Monitor types are define in SCL1.H :
  14881.  
  14882.              VC_MDA    = Monochrome
  14883.              VC_CGA    = CGA monitor
  14884.              VC_EGA    = EGA monitor
  14885.              VC_EGAM   = EGA with monochrome monitor
  14886.              VC_PGC    = Professional graphic
  14887.              VC_VGAM   = VGA / monochrome
  14888.              VC_VGA    = VGA
  14889.              VC_MCGADC = MCGA Digital
  14890.              VC_MCGAAM = MCGA Analog/mono
  14891.              VC_MCGAAC = MCGA Analog/color
  14892.  
  14893.           If you do not need all the video information you can call Video.
  14894.           This functions returns wether the monitor is color or mono:
  14895.  
  14896.              if(Video()==COLOR)
  14897.                 color monitor
  14898.              else
  14899.                 mono monitor
  14900.  
  14901.           NOTE: COLOR & MONO are defined in SCL1.H as the segment address
  14902.           of the Video Buffer (0xb800 for color 0xb000 for mono).
  14903.  
  14904.  
  14905.  
  14906.                                      Page -248-
  14907.  
  14908.  
  14909.  
  14910.  
  14911.  
  14912.                                     Appendix "C"
  14913.  
  14914.           SCL1 video functions work only in alphanumeric video modes.  You
  14915.           can initialize your system to one of this modes (3 in case of
  14916.           color, 7 in case of mono) by calling InitVideo at the beginning
  14917.           of your program.  Most of the times this won't be necessary since
  14918.           they are the default modes, but is not a bad idea to use
  14919.           InitVideo just to make sure.  Be aware that when you call
  14920.           InitVideo the screen will be cleared and the cursor moved to the
  14921.           screen's home position. Remember that version 2.0 of SCL1
  14922.           supports only video modes 0 - 3 and 7.
  14923.  
  14924.           SCL1's screen related functions always write to the active video
  14925.           page. You can change the video page using SetVideoPage. Be sure
  14926.           to specify a valid page for your system. You can force a function
  14927.           to write to a non-active video page by modifying the VC_Page
  14928.           variable before calling the desired video function, be sure to
  14929.           restore the correct value of VC_Page.
  14930.  
  14931.           Retrace will be done only if a CGA type adapter is found.  SCL1
  14932.           functions will not wait for the video retrace if an EGA adapter
  14933.           is found.  Yet you can force them to do the retrace by changing
  14934.           the variable VC_Retrace to 1. For example:
  14935.  
  14936.              if(Video()==COLOR)
  14937.                 VC_Retrace=1;
  14938.  
  14939.           You must set this variable to 1 AFTER having called Video or any
  14940.           other screen related function.
  14941.  
  14942.           EGA 43 lines and VGA 50 lines are now supported by SCL1.
  14943.           SetVideo4350 sets the mode to 43 or 50 lines depending on the
  14944.           monitor you have. SetVideo25 restores video mode to the default
  14945.           25 lines.
  14946.  
  14947.  
  14948.  
  14949.  
  14950.  
  14951.  
  14952.  
  14953.  
  14954.  
  14955.  
  14956.  
  14957.  
  14958.  
  14959.  
  14960.  
  14961.  
  14962.  
  14963.  
  14964.  
  14965.                                      Page -249-
  14966.  
  14967.  
  14968.  
  14969.  
  14970.  
  14971.                                     Appendix "D"
  14972.  
  14973.  
  14974.                                   SCL1 HEADER FILES
  14975.  
  14976.              SCL1.H -  SCL1 structures, functions prototypes and constant
  14977.                        definitions.
  14978.  
  14979.           SCL1KEYS.H - SCAN-ASCII code of most used keys. F1 - F10 (with
  14980.                        shift, alt and control), numeric key-pad keys and A-
  14981.                        Z (with alt and control) are defined.
  14982.  
  14983.           SCL1CLOR.H - Color definitions. 
  14984.  
  14985.                    Example: WHITE_BLUE stands for white characters on blue
  14986.                    background. 
  14987.  
  14988.                    Colors can be highligted and the blink attribute is also
  14989.                    defined. Example:
  14990.  
  14991.                    WHITE_RED | HIGHLIGHT
  14992.                    WHITE_RED | BLINK
  14993.  
  14994.           SCL1SND.H -  Definition of musical notes frequency in hertz to be
  14995.                        used with sound related functions.
  14996.  
  14997.                        Syntax  TS_X[y]?    , were:
  14998.  
  14999.                        TS = TSound id
  15000.                        X = musical note (C,D,E,F,G,A,B)
  15001.                        y = s means sharp, f means flat (optional)
  15002.                        ? = octave (1 - 7)
  15003.  
  15004.                        Examples:  TS_Df4 = D flat, fourth octave
  15005.                             TS_C4 = C, fourth octave (middle C)
  15006.  
  15007.           SCL1OLD.H -  Use this file only to compile source-code developed
  15008.                        with SCL1 version 1. Several global variables names
  15009.                        and constant definitions has changed in version 2.
  15010.                        SCL1OLD.H redefines older names to the new names
  15011.                        used in SCL1 version 2.
  15012.  
  15013.  
  15014.  
  15015.  
  15016.  
  15017.  
  15018.  
  15019.  
  15020.  
  15021.  
  15022.  
  15023.  
  15024.                                      Page -250-
  15025.  
  15026.  
  15027.  
  15028.  
  15029.  
  15030.                                     Appendix "E"
  15031.  
  15032.  
  15033.                                 DIALOG TYPE FUNCTIONS
  15034.  
  15035.           OVERVIEW
  15036.  
  15037.           In this version of SCL1 several new functions have been added
  15038.           that utilize a dialog scheme.  The idea behind these functions is
  15039.           to make them as flexible as possible, permitting the programmer
  15040.           to set or specify almost any available parameter.  This
  15041.           flexibility adds complexity and, in order to make them as
  15042.           friendly as possible, a dialog scheme has been used.
  15043.  
  15044.           During program development a need arises to perform complex task. 
  15045.           For example; let's say you need to get user input, but you want
  15046.           to add the flexibility of being able to check for a help key or
  15047.           for a keystroke combination that will insert a block at the
  15048.           current cursor position. Or you need a window were the user can
  15049.           browse through a list of items, yet you want to know exactly at
  15050.           any moment what item is being highlighted by the user so that you
  15051.           can display help information or show the selected item in another
  15052.           window.  These types of requirements usually require you to write
  15053.           a custom procedure.  Most library functions are not designed to
  15054.           handle these special requirements. The dialog type functions have
  15055.           been designed to permit you to handle these types of problems.
  15056.  
  15057.           To permit this level of flexibility, the dialog type functions
  15058.           make use of a message interchange scheme.  You can call the
  15059.           function as many times as required, each time requesting a given
  15060.           action.  The function will return a message that gives you the
  15061.           results or status of the requested action.
  15062.  
  15063.           The general way to use this functions is as follows:
  15064.  
  15065.           You can first call the function with an initialization message.
  15066.           This will take care of initializing the structure elements to
  15067.           some predetermined values and setting the function's initial
  15068.           conditions.  Then you can call the function with a message
  15069.           requesting a display.  This will instruct the function to draw or
  15070.           display to the screen the desired object (like a scroll window
  15071.           display).  Now that there is a display you will like to make the
  15072.           function active so that it can perform the desired task.  While
  15073.           the function is active it will keep sending back messages
  15074.           informing you of what is happening, for example, that an illegal
  15075.           key has been pressed (so display an error or help message, or
  15076.           beep the console to warn the user, etc.) or that the cursor has
  15077.           changed position, etc.  You can then analyze these returned
  15078.           messages and respond with a given action or you can ignore them.
  15079.           In fact, you can request the function to do anything it is
  15080.           capable of doing, for example, in the case of data entry field
  15081.           (like LineEditor), to move the cursor to any position, reformat
  15082.  
  15083.                                      Page -251-
  15084.  
  15085.  
  15086.  
  15087.  
  15088.  
  15089.                                     Appendix "E"
  15090.  
  15091.           or even change the data, insert a new character, etc. The
  15092.           messages have been defined in the header file as english-like
  15093.           messages to permit a friendly interface.
  15094.  
  15095.           Most of the parameters needed to configure the functions are
  15096.           included as elements of one or several structures.  These
  15097.           structure(s) need to be initialized before any call to the
  15098.           function is made.  The structures contain a lot of parameters and
  15099.           it might look as if they involve a lot of effort to define them. 
  15100.           With the aid of SSG (SCL1 Screen Generator program) you can
  15101.           define these structures very easily.  Please refer to the SSG
  15102.           reference manual included in this package.
  15103.  
  15104.           SENDING MESSAGES TO DIALOG TYPE FUNCTIONS
  15105.  
  15106.           Every effort has been made to make the dialog functions as
  15107.           uniform as possible.  Most functions use the same messages to
  15108.           perform the same tasks.
  15109.  
  15110.              INITIALIZING THE PARAMETER STRUCTURES:
  15111.  
  15112.                 You can define the parameter structures in two different
  15113.                 ways.  One way is to indicate a value for each parameter. 
  15114.                 The other way is to call the functions with a "INIT"
  15115.                 message, this will assign default values to most
  15116.                 parameters, then you can modify them according to your
  15117.                 taste.  Which method to use depends on how many of the
  15118.                 parameters you will like to have control of.
  15119.  
  15120.                 For example, let us initialize a ScrollWindow structure
  15121.                 using the two methods:
  15122.  
  15123.                 1) Using SW_INIT message:
  15124.  
  15125.                 #include <scl1.h>
  15126.  
  15127.                 /* This is the data you want to display in your 
  15128.                    scroll window */
  15129.  
  15130.                 char *swdbuf[]={
  15131.                    "First Item",
  15132.                    "Second Item",
  15133.                    0};
  15134.  
  15135.                 main()
  15136.                 {
  15137.                    SWData swd;
  15138.  
  15139.  
  15140.  
  15141.  
  15142.                                      Page -252-
  15143.  
  15144.  
  15145.  
  15146.  
  15147.  
  15148.                                     Appendix "E"
  15149.  
  15150.                    /* This initializes the structures to certain
  15151.                       default values (see each function description
  15152.                       for details). Once it has been initialized you
  15153.                       need to modify only the desired parameters */
  15154.  
  15155.                    ScrollWindow(SW_INIT,&swd);
  15156.  
  15157.                    /* Modify the size of our scroll window */
  15158.  
  15159.                    swd.UpperRow=6;
  15160.                    swd.LeftCol=26;
  15161.                    swd.LowerRow=17;
  15162.                    swd.RightCol=52;
  15163.  
  15164.                    /* And specify our data address */
  15165.  
  15166.                    swd.Buffer=swdbuf;
  15167.  
  15168.                 2) Defining the structure as static data:
  15169.  
  15170.                 #include <scl1.h>
  15171.  
  15172.                 /* This is the data you want to display in your
  15173.                    scroll window */
  15174.  
  15175.                 char *swdbuf[]={
  15176.                    "First Item",
  15177.                    "Second Item",
  15178.                    0};
  15179.  
  15180.                 /* All the parameters required to define the Scroll
  15181.                    Window go into this structure (size, color,
  15182.                    position, etc.). */
  15183.  
  15184.                 SWData swd={7,15,6,26,17,52,0,1,15,swdbuf,0,0," Scroll  
  15185.                 Window",7,0,0,0,0,0,0,0,0,0,0,0,0,0};
  15186.  
  15187.                 /* Since all the parameters have been defined there is
  15188.                    no need to change any of them */
  15189.  
  15190.              THE "RESET" MESSAGE:
  15191.  
  15192.                 Dialog function structures have several position related
  15193.                 variables.  When you declare your structure as static data
  15194.                 you do not need to call the function with an "INIT"
  15195.                 message.  You should call the function with a "RESET"
  15196.                 message to make sure that all these variables are reset.
  15197.                 This message also checks for undefined ExitKeys an sets
  15198.                 this element to default values if the have not been
  15199.                 defined.
  15200.  
  15201.                                      Page -253-
  15202.  
  15203.  
  15204.  
  15205.  
  15206.  
  15207.                                     Appendix "E"
  15208.  
  15209.                 Let us continue with the previous example of an application
  15210.                 of the ScrollWindow function.  Let us assume that the
  15211.                 structure has been defined as static data.  Our program
  15212.                 should look like this:
  15213.  
  15214.                 main()
  15215.                    {
  15216.  
  15217.                    /* The RESET message resets the internal position
  15218.                     related variables (in this case, it makes sure that
  15219.                     we start at the first item. It also checks for any
  15220.                     parameter that may have not been specified in the
  15221.                     structure (in this example the ExitKeys have not
  15222.                     been specified). You should always call a dialog
  15223.                     function using the "RESET" message when you are not
  15224.                     using the "INIT" message unless you desire the
  15225.                     cursor to appear over an specific item */
  15226.  
  15227.                    ScrollWindow(SW_RESET,&swd);
  15228.                    }
  15229.  
  15230.              THE "DRAW" MESSAGE:
  15231.  
  15232.                 Once your structure is defined and initialized there a lot
  15233.                 messages that you can send to it.  The first message
  15234.                 usually is "DRAW", this message instructs the function to
  15235.                 display the information to the screen.
  15236.  
  15237.                 In our example using the ScrollWindow function the "DRAW"
  15238.                 message should be sent like this:
  15239.  
  15240.                 ScrollWindow(SW_DRAW,&swd);
  15241.  
  15242.                 After sending this message you should see a the Scroll
  15243.                 Window displayed in the screen.
  15244.  
  15245.              THE "ACTIVE" MESSAGE:
  15246.  
  15247.                 The "ACTIVE" message permits you to have the function
  15248.                 perform the specific task it has been designed to do.
  15249.                 Messages are constantly returned by the dialog type
  15250.                 function.  If you are using the LineEditor function, the
  15251.                 "ACTIVE" message permits you to edit the entry field, for
  15252.                 the ScrollWindow function, this message lets you browse
  15253.                 through the window, etc.
  15254.  
  15255.  
  15256.  
  15257.  
  15258.  
  15259.  
  15260.                                      Page -254-
  15261.  
  15262.  
  15263.  
  15264.  
  15265.  
  15266.                                     Appendix "E"
  15267.  
  15268.                 When you send this message the function will retain the
  15269.                 program control until some event occurs.  For example, in
  15270.                 the case of ScrollWindow, when the user press the DOWN or
  15271.                 UP arrow keys to change the highlighted item, ScrollWindow
  15272.                 will return a NEW_POSITION message, or if you pressed an
  15273.                 undefined key (it could be F1 to request Help) an
  15274.                 ILLEGAL_KEY message is returned.  You can ignore the
  15275.                 returned message or respond to it.  In our previous example
  15276.                 of a the ScrollWindow function the code should look like
  15277.                 this:
  15278.  
  15279.                 do
  15280.                    {
  15281.                    Mess=ScrollWindow(SW_BROWSE,&swd);
  15282.                    }while(Mess != SW_EXIT_KEY);
  15283.  
  15284.                 Since when an "ACTIVE" message is sent the function retains
  15285.                 the program control until an event occurs, we should place
  15286.                 this function call within in a loop.  In this case any
  15287.                 returned message is ignored except the "EXIT_KEY" message
  15288.                 which means that a key defined as an exit key has been
  15289.                 pressed.  The user will be able to browse until one of
  15290.                 these keys is pressed.  Exit Keys can individually be
  15291.                 defined for each function.  You can add any desired Exit
  15292.                 Keys by defining a null-terminated array were all the
  15293.                 ExitKeys' SCAN/ASCII codes values are specified, for
  15294.                 example:
  15295.  
  15296.                 unsigned int MyExitKeys[]={ESC,ENTER,0};
  15297.  
  15298.                 NOTE: This example needs header file SCL1KEYS.H.
  15299.  
  15300.                 Once you have defined your Exits Keys you initialize the
  15301.                 structure ExitKeys element:
  15302.  
  15303.                 swd.ExitKeys=MyExitKeys;
  15304.  
  15305.                 You can also call the function with the "INIT" and "RESET"
  15306.                 messages to set the ExitKeys to default values (see each
  15307.                 function description)
  15308.  
  15309.              THE "POSITION_BEGIN" MESSAGE
  15310.  
  15311.                 When you call the function with this message the cursor
  15312.                 moves to the start of the data buffer.
  15313.  
  15314.  
  15315.  
  15316.  
  15317.  
  15318.  
  15319.                                      Page -255-
  15320.  
  15321.  
  15322.  
  15323.  
  15324.  
  15325.                                     Appendix "E"
  15326.  
  15327.              The "POSITION_END" MESSAGE
  15328.  
  15329.                 When you call the function with this message the cursor
  15330.                 moves to the end of the data buffer.
  15331.  
  15332.              The "POSITION_UP" MESSAGE
  15333.  
  15334.                 When you call the function with this message the cursor
  15335.                 moves one position towards the end of the data buffer in
  15336.                 the LineEditor function, to the next field for the Fields2
  15337.                 function and to the next item in all other functions.
  15338.  
  15339.              The "POSITION_DOWN" MESSAGE
  15340.  
  15341.                 When you call the function with this message the cursor
  15342.                 moves one position towards the start of the data buffer in
  15343.                 the LineEditor function, to the next field for the Fields2
  15344.                 function and to the next item in all other functions.
  15345.  
  15346.              The "SET_POSITION" MESSAGE
  15347.  
  15348.                 When you call the function with this message the cursor
  15349.                 moves to the specified position.  This function call
  15350.                 requires you to send an additional parameter (see
  15351.                 explanation below).
  15352.  
  15353.              The "CHECK_MOUSE" MESSAGE
  15354.  
  15355.                 Normally Dialog type functions handle the mouse input by
  15356.                 themselves but when you have several Dialog type functions
  15357.                 at the same time on the screen and your program detects
  15358.                 that the mouse has been clicked you can send this message
  15359.                 to any dialog function.  If the mouse was clicked inside a
  15360.                 function screen area it will return a MY_MOUSE message, in
  15361.                 any other case it returns a MOUSE_EVENT message.  This call
  15362.                 is useful for determining under what conditions the mouse
  15363.                 has been clicked.
  15364.  
  15365.           MESSAGES THAT DIALOG TYPE FUNCTIONS CAN RETURN
  15366.  
  15367.              THE "OK" MESSAGE.
  15368.  
  15369.                 This message is returned when you have called a Dialog type
  15370.                 function with the "DRAW", "INIT" or "RESET" messages, and
  15371.                 the action was performed as requested.
  15372.  
  15373.  
  15374.  
  15375.  
  15376.  
  15377.  
  15378.                                      Page -256-
  15379.  
  15380.  
  15381.  
  15382.  
  15383.  
  15384.                                     Appendix "E"
  15385.  
  15386.              THE "EXIT_KEY" MESSAGE.
  15387.  
  15388.                 This message is returned when one of the keys, defined as
  15389.                 an Exit Key, has been pressed.  It's SCAN/ASCII code is
  15390.                 stored in the structure element "EventInfo".
  15391.  
  15392.              THE "ILLEGAL_KEY" MESSAGE:
  15393.  
  15394.                 Each function uses several keys (like PgUp, PgDn etc.) to
  15395.                 perform common operations and checks for the use of the
  15396.                 defined ExitKeys. If any other key is pressed, it returns
  15397.                 an ILLEGAL_KEY message and stores the key's SCAN/ASCII code
  15398.                 in the structure's EventInfo element.
  15399.  
  15400.                 You can respond to this message for performing a given
  15401.                 action.  Let us see an example in which we use the
  15402.                 ILLEGAL_KEY message to display a help screen and at the
  15403.                 same time display the highlighted item in a secondary
  15404.                 window:
  15405.  
  15406.                 do
  15407.                    {
  15408.                    Mess=ScrollWindow(SW_ACTIVE,&swd);
  15409.  
  15410.                    if(Mess==SW_ILLEGAL_KEY)  /* Illegal key pressed? */
  15411.  
  15412.                        {
  15413.  
  15414.                        /* The structure's EventInfo element is common to
  15415.                           all Dialog function. It holds the value of the
  15416.                           key that was pressed when you receive and
  15417.                           EXIT_KEY or ILLEGAL KEY message. */
  15418.  
  15419.                        if(swd.EventInfo == F1)    /* Help Key? */
  15420.  
  15421.                        ... Display help code would go here ....
  15422.  
  15423.                    else              /* Unknown key */
  15424.  
  15425.                        ... Display error message, beep etc.
  15426.  
  15427.                        }
  15428.  
  15429.                        /* Let's now display the highlighted item in a
  15430.                           secondary window, the structure Position
  15431.                           element can be used as an index to our data
  15432.                           array */
  15433.  
  15434.                        WriteScreen(7,24,30,swdbuf[swd.Position]);
  15435.                    }while(Mess != SW_EXIT_KEY);
  15436.  
  15437.                                      Page -257-
  15438.  
  15439.  
  15440.  
  15441.  
  15442.  
  15443.                                     Appendix "E"
  15444.  
  15445.                 You can send other messages while you're inside this loop.
  15446.                 For example, in this loop the item at the cursor position
  15447.                 is deleted from the list when the DELETE key is pressed:
  15448.  
  15449.                 do
  15450.                    {
  15451.                    Mess=ScrollWindow(SW_BROWSE,&swd);
  15452.  
  15453.                    if(Mess == SW_ILLEGAL_KEY && swd.EventInfo == DEL)
  15454.  
  15455.                        {
  15456.  
  15457.                        /* DeleteItem would be an user defined function
  15458.                           that deletes an item from your list */
  15459.  
  15460.                        DeleteItem(swd.Position);
  15461.  
  15462.                        /* Now redraw your data */
  15463.  
  15464.                    Mess=ScrollWindow(SW_DRAW,&swd);
  15465.  
  15466.                    }while(Mess != SW_EXIT_KEY);
  15467.  
  15468.              THE "MOUSE EVENT" MESSAGE
  15469.  
  15470.                 This message is returned when the mouse has been clicked
  15471.                 outside the function screen area.  You can check mouse
  15472.                 variables MSE_LpX and MSE_LpY to get the actual position
  15473.                 were the mouse was clicked.
  15474.  
  15475.              THE "MY_MOUSE" MESSAGE
  15476.  
  15477.                 When you send a "CHECK_MOUSE" message to a dialog function
  15478.                 it checks if the mouse was clicked inside it's screen area.
  15479.                 In this case it will return a "MY_MOUSE" message. You can
  15480.                 then send an "ACTIVE" messages so that the function gets
  15481.                 control and services the mouse event.  In the case the
  15482.                 mouse was clicked outside it's screen area a "MOUSE_EVENT"
  15483.                 message is returned.
  15484.  
  15485.              THE "BUFFER_END" MESSAGE
  15486.  
  15487.                 This message is returned when the user has tried to move
  15488.                 the cursor passed the last element (or end) of the buffer.
  15489.                 This message can be safely ignored unless you want to
  15490.                 display an error or warning. (This message is not supported
  15491.                 by all Dialog functions).
  15492.  
  15493.  
  15494.  
  15495.  
  15496.                                      Page -258-
  15497.  
  15498.  
  15499.  
  15500.  
  15501.  
  15502.                                     Appendix "E"
  15503.  
  15504.              THE "BUFFER_BEGIN" MESSAGE
  15505.  
  15506.                 This message is returned when the user has tried to move
  15507.                 the cursor passed the first element (or beginning) of
  15508.                 buffer. This message can be safely ignored unless you want
  15509.                 to display an error or warning. (This message is not
  15510.                 supported by all Dialog functions).
  15511.  
  15512.              THE "ILLEGAL_POSITION" MESSAGE
  15513.  
  15514.                 This message is returned when you send a "SET_POSITION"
  15515.                 message but the position parameter is not valid.
  15516.  
  15517.              THE "NEW_POSITION" MESSAGE
  15518.  
  15519.                 This message is returned when the user has moved the cursor
  15520.                 to a new position. You can get the current position from
  15521.                 the "Position" structure element.
  15522.  
  15523.           Every effort has been made to make these functions to be called
  15524.           very similarly.
  15525.  
  15526.  
  15527.           STRUCTURE ELEMENTS COMMON TO ALL DIALOG FUNCTIONS:
  15528.  
  15529.           The following structure elements are common to all Dialog type
  15530.           functions:
  15531.  
  15532.               Colors - Colors are defined using one or more of the
  15533.                        following structure elements:
  15534.  
  15535.                      Color -   For functions that use only one color.
  15536.  
  15537.                 Functions that use more than one color:
  15538.  
  15539.                     NColor -   Normal Color
  15540.                     RColor -   Reversed Color
  15541.                     HColor -   Highlight Color
  15542.                     TColor -   Color used to tag items.
  15543.  
  15544.             Screen Position -  Screen coordinates are specified using one
  15545.                                or more of the following structure elements:
  15546.  
  15547.                    Row,Col - Row & column position.
  15548.  
  15549.                    UpperRow,LowerRow,LeftCol,RightCol - Used in functions
  15550.                    that must define a screen area. UpperRow/LeftCol
  15551.                    indicate the window's top left coordinate and
  15552.                    LowerRow/RightCol the lower right corner.
  15553.  
  15554.  
  15555.                                      Page -259-
  15556.  
  15557.  
  15558.  
  15559.  
  15560.  
  15561.                                     Appendix "E"
  15562.  
  15563.              EventInfo - When the user press an undefined key or an exit
  15564.                          key it's SCAN/ASCII code value is stored in this
  15565.                          element.
  15566.  
  15567.              ExitKeys -  Pointer to a null-terminated array of unsigned
  15568.                          integers. It must be initialized to the SCAN/ASCII
  15569.                          code values of the keys that are to be defined as
  15570.                          ExitKeys. (see the examples above). 
  15571.  
  15572.                 NOTE: ExitKeys are checked by Dialog Functions before the
  15573.                 default editing keys. This means you can override a defined
  15574.                 editing key or invalidate its use by defining it as an
  15575.                 ExitKey.
  15576.  
  15577.              Position -  This element holds the current cursor position.
  15578.                          Some functions may have more than one variable.
  15579.  
  15580.           ADDITIONAL PARAMETERS 
  15581.  
  15582.              Some messages (for example SET_POSITION) require that you send
  15583.           an additional parameter. This parameter is always the last
  15584.           parameter:
  15585.  
  15586.              NewPosition=123;
  15587.              ScrollWindow(SW_SET_POSITION,&swd,NewPosition);
  15588.  
  15589.           In this example, the new position is specified by the NewPosition
  15590.           variable.
  15591.  
  15592.           FUNCTIONS DERIVED FROM DIALOG FUNCTIONS
  15593.  
  15594.           Dialog functions offer a lot of power and flexibility.  Several
  15595.           of the new functions included in this version of SCL1 utilize
  15596.           them.  These new functions follow the general working procedure
  15597.           of the "INIT", "RESET", "DRAW" and "ACTIVE" messages previously
  15598.           described, but the retain the program control until on of the
  15599.           ExitKeys is pressed.  In future versions of SCL1 a monitoring
  15600.           facility will be added to this functions to improve their
  15601.           flexibility.  The FileBox2 and WFileBox are examples of these
  15602.           dialog derived functions.  The next example shows how to use
  15603.           these functions:
  15604.  
  15605.  
  15606.  
  15607.  
  15608.  
  15609.  
  15610.  
  15611.  
  15612.  
  15613.  
  15614.                                      Page -260-
  15615.  
  15616.  
  15617.  
  15618.  
  15619.  
  15620.                                     Appendix "E"
  15621.  
  15622.              #include <scl1.h>
  15623.  
  15624.              main()
  15625.              {
  15626.              FBData fbd;
  15627.              char buffer[80];
  15628.  
  15629.              memset(buffer,0,sizeof(buffer));
  15630.              FileBox2(FB_INIT,&fbd); /* Initialize */
  15631.  
  15632.              fbd.UpperRow=10;     /* Modify size & position */
  15633.              fbd.LeftCol=20;
  15634.              fbd.LowerRow=20;
  15635.              fbd.RightCol=60;
  15636.              fbd.Buffer=buffer;      /* Use our buffer */
  15637.  
  15638.              FileBox2(FB_DRAW,&fbd);
  15639.              FileBox2(FB_ACTIVE,&fbd);
  15640.              }
  15641.  
  15642.           Its important to know if a function is a true DIALOG function or
  15643.           a DIALOG-DERIVED function.
  15644.  
  15645.  
  15646.  
  15647.  
  15648.  
  15649.  
  15650.  
  15651.  
  15652.  
  15653.  
  15654.  
  15655.  
  15656.  
  15657.  
  15658.  
  15659.  
  15660.  
  15661.  
  15662.  
  15663.  
  15664.  
  15665.  
  15666.  
  15667.  
  15668.  
  15669.  
  15670.  
  15671.  
  15672.  
  15673.                                      Page -261-
  15674.  
  15675.  
  15676.  
  15677.  
  15678.  
  15679.                                     Appendix "F"
  15680.  
  15681.  
  15682.                              CHANGES IN SCL1 version 2.0
  15683.  
  15684.           For several reasons we have been forced to make various changes
  15685.           that make version 2.0 incompatible with version 1.1 in some
  15686.           aspects:
  15687.  
  15688.           SCL1's global variables -
  15689.  
  15690.              Some of SCL1's global variables were not originally intended
  15691.              to be made accessible to non-library functions, in fact some
  15692.              of them were not even documented.  They were given names in
  15693.              capital letters (like MOUSE_FLAG). This can create a confusion
  15694.              since capital letters are generally used in C language for
  15695.              #define directive constants.  We have changed all global
  15696.              variables names in order prevent this confusion . Every
  15697.              variable now has a prefix that identifies the function that
  15698.              declares the variable, for example all mouse variables start
  15699.              with MSE, while all Video variables declared in function
  15700.              VideoConfig start with VC.  Following the prefix is the
  15701.              variable name, for example MSE_MouseFl, VC_VideoSeg etc.  If
  15702.              you have a big program that uses a lot of these variables and
  15703.              you don't want to change them all you can use SCL1OLD.H header
  15704.              file that redefines all identifiers to new names. Take a look
  15705.              at this file for a complete list of modified variables.
  15706.  
  15707.           SCL1's constants -
  15708.  
  15709.              Several constants in SCL1 were not defined using uppercase as
  15710.              it is traditionally done in C.  For example in version 1.?
  15711.              "LETTER" is used by GetString to accept capitalize letters
  15712.              while "letter" to accept letters but without capitalization.
  15713.              In version 2.0 all constants are uppercase.  As with global
  15714.              variables the SCL1OLD.H file redefines all identifiers to new
  15715.              names.
  15716.  
  15717.           Function arguments-
  15718.  
  15719.              Several SCL1 functions received arguments of type char. Most
  15720.              of the times is more efficient to pass arguments of the
  15721.              integer type even if the extra storage space is not needed.
  15722.              All arguments of type char has been modified to type integer.
  15723.              This should not represent problems but you should not mix
  15724.              program modules compiled using version 1 with modules compiled
  15725.              with version 2.
  15726.  
  15727.  
  15728.  
  15729.  
  15730.  
  15731.  
  15732.                                      Page -262-
  15733.  
  15734.  
  15735.  
  15736.  
  15737.  
  15738.                                     Appendix "F"
  15739.  
  15740.           New functions-
  15741.  
  15742.           Video related - SCL1 now supports CGA 40 columns mode as well as
  15743.           EGA 43 lines and VGA 50 lines video modes. Video-pages are also
  15744.           supported. The following new functions have been added:
  15745.  
  15746.                    Center
  15747.                    DrawBoxLine
  15748.                    DrawLine
  15749.                    ErrorShadowOff
  15750.                    ErrorShadowOn
  15751.                    FillBlock
  15752.                    Int24ShadowOff
  15753.                    Int24ShadowOn
  15754.                    MessageShadowOff
  15755.                    MessageShadowOn
  15756.                    PushCursor
  15757.                    PopCursor
  15758.                    SetInt24Colors
  15759.                    SetErrorBoxColor
  15760.                    SetDialogColor
  15761.                    SetShadowColor
  15762.                    SetUserBox
  15763.                    SetUserBoxLine
  15764.                    SetVideoMode
  15765.                    SetVideoPage
  15766.                    SetVideo4350
  15767.                    SetVideo25
  15768.                    VideoConfig
  15769.                    WriteOffLen
  15770.                    WriteOffset
  15771.                    WriteScreenLen
  15772.                    YesNoShadowOff
  15773.                    YesNoShadowOn
  15774.  
  15775.           Dialog functions - This is probably the most important addition
  15776.           to version 2. Please refer to Dialog Functions (Appendix "E").
  15777.           New functions:
  15778.  
  15779.                    Calendar
  15780.                    FieldCheck
  15781.                    Fields2
  15782.                    FileBox2
  15783.                    LineEditor
  15784.                    ListWindow
  15785.                    LW_MoveTo
  15786.                    MenuSystem
  15787.                    MouseButton
  15788.                    ScrollWindow
  15789.                    Select
  15790.  
  15791.                                      Page -263-
  15792.  
  15793.  
  15794.  
  15795.  
  15796.  
  15797.                                     Appendix "F"
  15798.  
  15799.                    SW_MoveTo
  15800.                    TagList2
  15801.                    TextWindow
  15802.  
  15803.           Mouse functions - Double click is now supported. You can also
  15804.           modify the mouse cursor appearance. The InitMouse function
  15805.           simplifies initialization process. New functions:
  15806.  
  15807.                    InitMouse
  15808.                    ResetMouseCur
  15809.                    SetMouseCur
  15810.  
  15811.           File functions - Several optimizations have been performed. A bug
  15812.           in GetFileSize that trashed the file read/write pointer was
  15813.           fixed. FileBox has been greatly improved and several new options
  15814.           are available through the use of FileBox2 and WFileBox (see
  15815.           Dialog functions). New functions:
  15816.  
  15817.                    FindFirst
  15818.                    FindNext
  15819.  
  15820.  
  15821.  
  15822.  
  15823.  
  15824.  
  15825.  
  15826.  
  15827.  
  15828.  
  15829.  
  15830.  
  15831.  
  15832.  
  15833.  
  15834.  
  15835.  
  15836.  
  15837.  
  15838.  
  15839.  
  15840.  
  15841.  
  15842.  
  15843.  
  15844.  
  15845.  
  15846.  
  15847.  
  15848.  
  15849.  
  15850.                                      Page -264-
  15851.  
  15852.  
  15853.  
  15854.  
  15855.  
  15856.                                     Appendix "F"
  15857.  
  15858.  
  15859.                               REGISTRATION INFORMATION
  15860.  
  15861.           SCL1 C function Library Version 1.1 is copyrighted by José
  15862.           Rodríguez Alvira & José R. Lebrón.  You don't have to pay any
  15863.           royalties to use SCL1 in your programs.  To Register as a SCL1
  15864.           user and to obtain a copy of SCL1 libraries for the Small,
  15865.           Medium, Compact, Large and Huge memory models send $30.00 (or
  15866.           $60.00 to also get the source code) to:
  15867.  
  15868.                        José Rodríguez Alvira
  15869.                        El Monte Sur 190, Apt. B-342,
  15870.                        Hato Rey, Puerto Rico, 00918
  15871.  
  15872.           You will receive by mail the latest version of the SCL1 library
  15873.           for the compiler of your choice, and a free copy of a Full-Screen
  15874.           Extended ASCII Editor called SSG, that generates the source code
  15875.           of your screens using SCL1's functions (The SCL1DEMO was done
  15876.           with the help of SSG).  You will be notified of any future
  15877.           additions or revisions to SCL1 and of any other program
  15878.           developed.
  15879.  
  15880.           You are encouraged to share the Demo Distribution disk with your
  15881.           friends.  The full version that you obtain upon registration is
  15882.           not intended for free distribution and should not be shared with
  15883.           others.
  15884.  
  15885.           The latest version of SCL1, sample programs and comments about
  15886.           these programs are available in:
  15887.  
  15888.                    TECH BBS (Sysop: José Romero)
  15889.                    (809)732-2322
  15890.  
  15891.           You can leave any comments, suggestions or questions in this BBS. 
  15892.           We will reply these messages in the same BBS.
  15893.  
  15894.  
  15895.  
  15896.  
  15897.  
  15898.  
  15899.  
  15900.  
  15901.  
  15902.  
  15903.  
  15904.  
  15905.  
  15906.  
  15907.  
  15908.  
  15909.                                      Page -265-
  15910.